home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr44 / tge141.zip / TGE.DOC < prev    next >
Text File  |  1995-01-23  |  134KB  |  2,696 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                The Graphics Engine version 1.41 Documentation
  7.                               23 January 1995
  8.  
  9.                 The Graphics Engine software and manual are
  10.                Copyright (c) 1993-1995 by Matthew Hildebrand.
  11.                             All rights reserved.
  12.  
  13.  
  14.  
  15.  
  16. Topics covered in this document:
  17. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  18.  
  19.      INTRODUCTION
  20.      WHY USE TGE?
  21.      TERMS OF USAGE AND DISTRIBUTION
  22.      SYSTEM REQUIREMENTS
  23.      PACKING LIST
  24.      RELEASE NOTES FOR VERSION 1.41
  25.      A CRASH COURSE IN GRAPHICS PROGRAMMING
  26.      USING TGE IN A PROGRAM
  27.      TGE'S GRAPHICAL FUNCTION SET
  28.      VIEWPORTS AND CLIPPING
  29.      VIRTUAL COORDINATES
  30.      VIRTUAL SCREENS
  31.      GRAPHICAL OUTPUT MODES
  32.      USING FONTS
  33.      BITMAP MANIPULATION
  34.      PALETTE MANIPULATION
  35.      USING THE MOUSE
  36.      TGE'S MOUSE FUNCTION SET
  37.      ADDITIONAL FEATURES IN THE REGISTERED VERSION
  38.      CREATING FONTS
  39.      USING PCX2RAW AND GRAPHICS FILES
  40.      WHICH SVGA VIDEO DRIVER SHOULD I USE?
  41.      CONTACTING THE AUTHOR
  42.      OBTAINING THE NEWEST VERSION OF TGE
  43.      TROUBLESHOOTING
  44.      ACKNOWLEDGEMENT
  45.      LEGAL STUFF
  46.  
  47.  
  48.  
  49.  
  50. INTRODUCTION
  51. ▀▀▀▀▀▀▀▀▀▀▀▀
  52.  
  53.      The Graphics Engine is the result of my efforts to construct a library
  54.      of routines designed to make writing C/C++ graphics applications
  55.      easier.  I have used it in my own programs with excellent results.
  56.  
  57.      TGE allows the DOS programmer to easily access many graphics modes,
  58.      without having to do special coding for each; the complications
  59.      involved with supporting more than one graphics mode are removed.  TGE
  60.      also provides remarkable flexibility and expandability through its
  61.      modular design.
  62.  
  63.  
  64.  
  65. WHY USE TGE?
  66. ▀▀▀▀▀▀▀▀▀▀▀▀
  67.  
  68.      TGE provides a simple, standard interface with which programs may
  69.      access a powerful library of graphical functions.  TGE supports
  70.      device-independence through the use of loadable drivers; loadable
  71.      fonts; viewports; virtual screens of definable sizes; graphics output
  72.      using COPY, AND, NOT, OR, and XOR, even to virtual screens; bitmap
  73.      scaling; interrupt-driven, definable mouse pointer services; direct
  74.      manipulation of PCX, RAW, and PAL files; and a virtual coordinate
  75.      system to make device-independence easier.
  76.  
  77.      TGE's use of loadable graphics drivers means that all code and data
  78.      necessary to handle any given graphics mode is stored in a disk file.
  79.      When a program runs, this file will be loaded into memory and the code
  80.      and data it contains will be made available.  Consequently:
  81.           - Support for more graphics modes may be added simply by creating
  82.             more drivers; programs need not be recompiled.
  83.           - Since the code to manage the specifics of each mode is
  84.             contained in the drivers, the main program needs not concern
  85.             itself with what mode it is operating in.  The same code can
  86.             work in any graphics mode.
  87.           - Memory is saved for programs which support many graphics modes.
  88.             Instead of keeping the code and data necessary for each in
  89.             memory at all times, only the memory required for one driver is
  90.             used.
  91.  
  92.      The names of TGE's functions, such as "putImage" and "filledRect", may
  93.      easily be changed to suit individual preferences.
  94.  
  95.      TGE is powerful, fast, and cheap.  Upgrades are free.
  96.  
  97.  
  98.  
  99. TERMS OF USAGE AND DISTRIBUTION
  100. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  101.  
  102.      TGE is not free; it is distributed on a "try before you buy" basis.
  103.      Permission is granted to use TGE, for evaluation purposes only, for a
  104.      trial period of up to 30 days.  In order to use TGE after the trial
  105.      period, you MUST REGISTER; registration entitles you to free upgrades,
  106.      technical support, royalty-free distribution rights for all software
  107.      written using TGE, and a copy of the registered version of TGE, which
  108.      includes TGE's complete source code, an extra font, and features not
  109.      available in the shareware version.  Failure to register constitutes
  110.      theft and is punishable by law.
  111.  
  112.      By registering a copy of TGE, you signify that you have read and
  113.      understood the terms of usage and distribution explained in this
  114.      document, and that you agree to be bound by these terms; you also
  115.      signify that you agree to release the Author (Matthew Hildebrand) from
  116.      all liability associated with the use of TGE.
  117.  
  118.      In order to register a copy of TGE, send $30 US funds or $40 Canadian
  119.      funds to Matthew Hildebrand at the address listed in the CONTACTING
  120.      THE AUTHOR section of this document.  For each software package which
  121.      is both distributed by a corporation and built using TGE, send an
  122.      additional $100 US funds or $130 Canadian funds (negotiable); this fee
  123.      is a pittance compared to the revenue generated by typical commercial
  124.      packages.  Payment by money order, cheque, or cash is acceptable;
  125.      currency must be US or Canadian funds.  Users outside the USA and
  126.      Canada, please ensure that cheques are drawn on a US or Canadian bank,
  127.      and that money orders are international if necessary.  Also, please
  128.      send a filled out copy of ORDER.FRM with your payment.  Thank you in
  129.      advance for registering TGE; your support is what makes its continued
  130.      growth possible.
  131.  
  132.      Upon receipt of your registration, I will mail you a copy of the
  133.      registered version of TGE, which includes complete source code, an
  134.      extra font, and features not available in the shareware version; this
  135.      registered copy of TGE may not be distributed in any way.  Once I have
  136.      mailed you a copy of the registered version, you will be considered a
  137.      registered user.  If you are interested in receiving notifications of
  138.      new versions as they are released, or copies of the new versions
  139.      themselves, refer to paragraph two of the OBTAINING THE NEWEST VERSION
  140.      OF TGE section.
  141.  
  142.      The privileges granted by purchasing TGE may be retracted if any of
  143.      the copyright notices in TGE's source files is modified or removed, if
  144.      any or all of the registered version of TGE is distributed in any way,
  145.      or if any or all of TGE's source code is distributed as part of a
  146.      software package.
  147.  
  148.      The shareware version of TGE may be distributed freely as long as the
  149.      distributed package is complete and its contents are not modified in
  150.      any way, and the distributed package is not sold for profit.
  151.  
  152.  
  153.  
  154. SYSTEM REQUIREMENTS
  155. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  156.  
  157.      TGE is a C/C++ programmer's library.  As such, it requires a C or C++
  158.      compiler of some sort to work with it.  TGE was written and tested
  159.      with Borland C++ 2.0 and Turbo C 2.0; it may work with other C/C++
  160.      compilers as well.
  161.  
  162.      The drivers that come with TGE are written using 80386 instructions;
  163.      they therefore cannot be used on a processor older than the 386 unless
  164.      they are modified first.
  165.  
  166.      The font and virtual coordinate systems are written in C++, not C.  In
  167.      order to use loadable fonts or VCOORD.H, a C++ compiler will be
  168.      required.
  169.  
  170.  
  171.  
  172. PACKING LIST
  173. ▀▀▀▀▀▀▀▀▀▀▀▀
  174.  
  175.      The current version of TGE consists of the following files:
  176.  
  177.      \TGE\               <DIR>
  178.          TGE.DOC                   TGE documentation.
  179.          QUICKREF.DOC              TGE function library quick reference.
  180.          REVISION.HST              Revision history.
  181.          USERSSAY.TXT              What users have to say about TGE.
  182.          CATALOG.TXT               Catalog of my software packages.
  183.          ORDER.FRM                 Order form (shareware version only).
  184.          UNIVESA.DOC               Universal VESA TSR documentation.
  185.          UNIVESA.EXE               Universal VESA TSR executable.
  186.          README.NOW                Important information.
  187.          FILE_ID.DIZ               Archive description file used by some
  188.                                      bulletin board systems (shareware
  189.                                      version only).
  190.      \TGE\INCLUDE\       <DIR> TGE include files.
  191.          TGE.H                     TGE main header file.
  192.          FIXFONT.H                 Fixed-size font header file (C++).
  193.          VARFONT.H                 Variable-sized font header file (C++).
  194.          TGEMOUSE.H                Mouse header file.
  195.          VCOORD.H                  Virtual coordinate system (C++).
  196.            (The licensed version contains complete source code.)
  197.        \TGE\LIB\         <DIR> Library directory.
  198.          BCL.LIB                   Borland C++ large model library.
  199.          BCH.LIB                   Borland C++ huge model library.
  200.          TGELIB.LST                Listfile used by library makefiles.
  201.          BCL.MAK                   Makefile for Borland C++ large model
  202.                                      library.
  203.          BCH.MAK                   Makefile for Borland C++ huge model
  204.                                      library.
  205.          UPDATE.BAT                Recompile the C++ portions of TGE, and
  206.                                      update BCL.LIB and BCH.LIB accordingly.
  207.        \TGE\UTIL\        <DIR> PCX2RAW and MAKEFONT utilitites.
  208.          PCX2RAW.C                 Source for PCX2RAW.
  209.          PCX2RAW.EXE               Convert PCX files to RAW and PAL files.
  210.          MAKEFONT.C                Source for MAKEFONT.
  211.          MAKEFONT.EXE              Make a font from individual bitmaps.
  212.        \TGE\DRIVERS\     <DIR> Loadable drivers.
  213.          320X200.DRV               Driver for VGA 320x200x256.
  214.          320X240.DRV               Driver for VGA 320x240x256.
  215.          320X400.DRV               Driver for VGA 320x400x256.
  216.          360X480.DRV               Driver for VGA 360x480x256.
  217.          640X480.DRV               Driver for SVGA 640x480x256.
  218.          800X600.DRV               Driver for SVGA 800x600x256.
  219.          1024X768.DRV              Driver for SVGA 1024x768x256.
  220.          VBE100.DRV                Driver for VBE SVGA 640x400x256.
  221.          VBE101.DRV                Driver for VBE SVGA 640x480x256.
  222.          VBE103.DRV                Driver for VBE SVGA 800x600x256.
  223.          VBE105.DRV                Driver for VBE SVGA 1024x768x256.
  224.          VBE107.DRV                Driver for VBE SVGA 1280x1024x256.
  225.        \TGE\FONTS\       <DIR> Loadable fonts.
  226.          BIGTEXT.FNT               Big letters (variable-sized).
  227.          8X8.FNT                   8x8 font (fixed-size).
  228.          8X14.FNT                  8x14 font (fixed-size).
  229.          8X16.FNT                  8x16 font (fixed-size).
  230.        \TGE\DEMO\        <DIR> Demo programs.
  231.          TGEDEMO.DOC               Documentation for demo program.
  232.          TGEDEMO.CPP               Source code for demo program.
  233.          MAKEFILE                  Makefile for the demo program.
  234.          TGEDEMO.EXE               TGE demo program executable.
  235.          TGELOGO.RAW               Data file used by the TGE demo program.
  236.          SIMPLE.CPP                A skeleton TGE program showing interface
  237.                                      basics.
  238.  
  239.      If you did not receive all of these files, you have an illegal copy of
  240.      The Graphics Engine.
  241.  
  242.  
  243.  
  244. RELEASE NOTES FOR VERSION 1.41
  245. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  246.  
  247.      BEFORE ATTEMPTING TO USE THE C++ PORTIONS OF TGE, BE SURE TO RECOMPILE
  248.      THEM ON YOUR MACHINE.  THIS IS NECESSARY TO AVOID WHAT APPEARS TO BE A
  249.      BUG IN TURBO LINKER.  IN ORDER TO RECOMPILE THE C++ PORTIONS, RUN
  250.      UPDATE.BAT FROM THE TGE\LIB DIRECTORY.
  251.  
  252.      For a complete list of changes, refer to the REVISION.HST file.
  253.  
  254.      The drivers used with this release are not compatible with those from
  255.      version 1.31 or older, since changes have been made to the driver
  256.      structure in order to allow for new features.
  257.  
  258.  
  259.  
  260. A CRASH COURSE IN GRAPHICS PROGRAMMING
  261. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  262.  
  263.      A graphics screen is composed of thousands or even hundreds of
  264.      thousands of coloured dots called "pixels".  Each pixel is referenced
  265.      according to its offset, in coordinate form, from the upper-left of
  266.      the screen:  (0,0), or the "origin".  The 'x' of a pixel's (x,y)
  267.      location signifies the column number, and the 'y' signifies the row
  268.      number; for example, a 640x480 screen would have (0,0) in the upper-
  269.      left and (639,479) in the lower-right.
  270.  
  271.      Each of these pixels has a colour which is recorded as a number,
  272.      ranging from 0..255 in 256-colour modes.  Each of these numbers is an
  273.      index into a table of colours which the video card maintains:  the
  274.      "palette".  The palette is what determines which colour is represented
  275.      by certain numbers; for instance, what colour is colour number 196?
  276.      Blue?  Green?  Purple?  It depends on the current setting of the
  277.      palette register for colour number 196.
  278.  
  279.      Each of these palette registers consists of three components:  the
  280.      red, green, and blue values, each of which is in the range 0..255.
  281.      All the displayable colours are composed of these three primary
  282.      colours in some proportion.  For instance, a purple would have lots of
  283.      red and blue, but little or no green.
  284.  
  285.      The palette can be a powerful tool, as changing palette register, say,
  286.      48, causes all pixels on-screen with the value of 48 to instantly
  287.      change to the new colour.  It is important to keep in mind that the
  288.      palette is a global palette; ie. it affects the entire screen.
  289.  
  290.      That's all there is to it!  <grin>
  291.  
  292.  
  293.  
  294. USING TGE IN A PROGRAM
  295. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  296.  
  297.      BEFORE ATTEMPTING TO USE THE C++ PORTIONS OF TGE, BE SURE TO RECOMPILE
  298.      THEM ON YOUR MACHINE.  THIS IS NECESSARY TO AVOID WHAT APPEARS TO BE A
  299.      BUG IN TURBO LINKER.  IN ORDER TO RECOMPILE THE C++ PORTIONS, RUN
  300.      UPDATE.BAT FROM THE TGE\LIB DIRECTORY.
  301.  
  302.      TGE now uses two environment variables:  TGEDRIVERS and TGEFONTS.
  303.      Though these environement variables are not necessary, it is
  304.      recommended that you add the following lines to your AUTOEXEC.BAT
  305.      file:
  306.           set TGEDRIVERS=drive:\tge\drivers\
  307.           set TGEFONTS=drive:\tge\fonts\
  308.      where 'drive:' is the drive on which you installed TGE.  The trailing
  309.      backslash is required.
  310.  
  311.  
  312.      Incorporating TGE into a program is an easy process involving three
  313.      simple steps.  First, you must be sure that TGE is recognized by the
  314.      program; to do so, #include the header file TGE.H into any source file
  315.      which accesses any of TGE's routines; you may also need to #include
  316.      other header files, such as TGEMOUSE.H if you use TGE's mouse code.
  317.      Also, ensure that the appropriate library file is linked in with the
  318.      program's OBJ files to make the EXE file; available library files are
  319.      BCL.LIB (Borland C++ large model) and BCH.LIB (Borland C++ huge
  320.      model).
  321.  
  322.      IF YOU WILL BE USING ANY FONTS, BE SURE TO RECOMPILE THE C++ PORTIONS
  323.      OF TGE PRIOR TO LINKING ANY PROGRAM.  IN ORDER TO RECOMPILE THE C++
  324.      PORTIONS, RUN UPDATE.BAT FROM THE TGE\LIB DIRECTORY.
  325.  
  326.      Second, a graphics driver MUST be loaded before any code or data
  327.      contained in the driver is accessed; results are undefined (though
  328.      almost certainly bad) if this step is not taken.  Code to load a
  329.      driver might look like this:
  330.  
  331.           if (loadGraphDriver(drvFileName) != TGE_SUCCESS)
  332.           {
  333.             printf("Error loading driver %s; aborting.\n\n", drvFileName);
  334.             exit(EXIT_FAILURE);
  335.           }
  336.           else
  337.             atexit(unloadGraphDriver);
  338.  
  339.      As its only parameter, loadGraphDriver() takes a string consisting of
  340.      the file name (which may include any valid DOS path) of the driver to
  341.      be loaded; note that if the specified filename cannot be found, TGE
  342.      will attempt to load it from the directory specified by the TGEDRIVERS
  343.      environment variable.  loadGraphDriver() returns TGE_SUCCESS if the
  344.      loading was successful, or one of TGE_OPEN_ERR (file not found),
  345.      TGE_FORMAT_ERR (file is not a valid TGE driver), TGE_ALLOC_ERR (out of
  346.      memory), and TGE_FILE_ERR (general file I/O error) if an error
  347.      occurred.  These macros are defined in TGE.H.
  348.  
  349.      Third, after TGE's graphical functions are no longer needed (usually
  350.      just before a program exit), the function unloadGraphDriver() should
  351.      be called.  It takes no parameters, and returns nothing.  It simply
  352.      frees the memory taken up by a driver after it has been loaded.  (With
  353.      some compilers it is not necessary to call this function, but it's
  354.      safer to call it just to be sure.)  It is generally a good idea to
  355.      place unloadGraphDriver() in the atexit() queue, as was done in the
  356.      above code fragment.
  357.  
  358.  
  359.      Note that the initGraphics() function must be called to enter graphics
  360.      mode; for more information, see the next section.  For more
  361.      information on how to use any particular feature, refer to the
  362.      appropriate section of this document.
  363.  
  364.  
  365.  
  366. TGE'S GRAPHICAL FUNCTION SET
  367. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  368.  
  369.      After a driver has been loaded, all of TGE's graphical functions can
  370.      be accessed.  To call a function, simply execute
  371.  
  372.           functionName(parameter_list);
  373.  
  374.      where "functionName" is the name of the desired function (eg.
  375.      "ellipse" or "filledRect") and "parameter_list" is all parameters to
  376.      that function, if any.
  377.  
  378.      A complete list of TGE's graphical functions follows.
  379.  
  380.  
  381.  *** Function:      initGraphics()
  382.      Syntax:        void initGraphics(void);
  383.      Purpose:       Initialize graphics mode.
  384.      Parameters:    None.
  385.      Return value:  1 on success or 0 on error.
  386.      Remarks:       None.
  387.      See also:      deInitGraphics()
  388.  
  389.  *** Function:      deInitGraphics()
  390.      Syntax:        void deInitGraphics(void);
  391.      Purpose:       Revert to 80x25 colour text mode.
  392.      Parameters:    None.
  393.      Return value:  None.
  394.      Remarks:       None.
  395.      See also:      initGraphics()
  396.  
  397.  *** Function:      putImage()
  398.      Syntax:        void huge putImage(int x, int y, void far *image);
  399.      Purpose:       Place a bitmap, or image, onto the screen.
  400.      Parameters:    The bitmap contained in 'image' will be placed onto the
  401.                     screen with its upper-left coordinate at ('x','y').
  402.      Return value:  None.
  403.      Remarks:            Clipping is performed; the image may be placed
  404.                     entirely on-screen, partially on-screen, or entirely
  405.                     off-screen.
  406.                          This function is declared as huge so that it will
  407.                     work properly when called from within an interrupt
  408.                     service routine.
  409.      See also:      putImageInv(), getImage(), imageSize(), imageSizeDim(),
  410.                     putHorizLine(), putHorizLineInv(), getHorizLine()
  411.  
  412.  *** Function:      putImageInv()
  413.      Syntax:        void huge putImageInv(int x, int y, void far *image);
  414.      Purpose:       Place a bitmap, or image, on the screen.
  415.      Parameters:    The bitmap contained in 'image' will be placed onto the
  416.                     screen with its upper-left coordinate at ('x','y').
  417.      Return value:  None.
  418.      Remarks:            Clipping is performed; the image may be placed
  419.                     entirely on-screen, partially on-screen, or entirely
  420.                     off-screen.    putImageInv() differs from putImage()
  421.                     only in that it allows for transparent, or invisible,
  422.                     colours.  If any pixel in the image buffer has a value
  423.                     of zero, the corresponding pixel on-screen will not be
  424.                     modified.  Using putImageInv() can avoid having black
  425.                     borders around non-rectangular shapes.
  426.                          This function is declared as huge so that it will
  427.                     work properly when called from within an interrupt
  428.                     service routine.
  429.      See also:      putImage(), getImage(), imageSize(), imageSizeDim(),
  430.                     putHorizLineInv(), putHorizLine(), getHorizLine()
  431.  
  432.  *** Function:      getImage()
  433.      Syntax:        void huge getImage(int ulx, int uly, int lrx, int lry,
  434.                     void far *image);
  435.      Purpose:       Copy the specified rectangular portion of the screen to
  436.                     memory.
  437.      Parameters:    The portion of the screen with its upper-left
  438.                     coordinate at ('ulx','uly') and its lower-left
  439.                     coordinate at ('lrx','lry') will be copied into the
  440.                     previously allocated memory region at 'image' (see
  441.                     imageSize()).
  442.      Return value:  None.
  443.      Remarks:            Clipping is performed.  Note that only the portion
  444.                     of the specified region which lies within the current
  445.                     viewport will be placed in the image buffer by
  446.                     getImage().  Be careful not to assume that a getImage()
  447.                     image has off-screen data in it.
  448.                          This function is declared as huge so that it will
  449.                     work properly when called from within an interrupt
  450.                     service routine.
  451.      See also:      putImage(), putImageInv(), imageSize(), imageSizeDim(),
  452.                     getHorizLine(), putHorizLine(), putHorizLineInv()
  453.  
  454.  *** Function:      imageSize()
  455.      Syntax:        unsigned long imageSize(int ulx, int uly, int lrx, int
  456.                     lry);
  457.      Purpose:       Determine the amount of memory required to hold a
  458.                     rectangular portion of the screen.
  459.      Parameters:    imageSize() will calculate the amount of memory
  460.                     required to hold the porion of the screen whose upper-
  461.                     left coordinate is ('ulx','uly') and whose lower-left
  462.                     coordinate is ('lrx','lry').
  463.      Return value:  imageSize returns an unsigned long containing the size
  464.                     of the area in bytes.
  465.      Remarks:            Clipping is performed.
  466.                          imageSize() is designed for use with putImage(),
  467.                     putImageInv(), and getImage().  To use it with
  468.                     putHorizLine() and getHorizLine(), subtract 4 from the
  469.                     value it returns.  (Image buffers have four bytes of
  470.                     dimension information in them; line buffers do not.)
  471.      See also:      imageSizeDim(), putImage(), putImageInv(), getImage(),
  472.                     putHorizLine(), getHorizLine()
  473.  
  474.  *** Function:      imageSizeDim()
  475.      Syntax:        unsigned long imageSizeDim(unsigned wide, unsigned
  476.                     deep);
  477.      Purpose:       Determine the amount of memory required to hold a
  478.                     rectangular portion of the screen.
  479.      Parameters:    imageSize() will calculate the amount of memory
  480.                     required to hold the porion of the screen with width
  481.                     'wide' and depth 'deep'.
  482.      Return value:  imageSize returns an unsigned long containing the size
  483.                     of the area in bytes.
  484.      Remarks:            Clipping is not performed.
  485.                          imageSizeDim() is designed for use with
  486.                     putImage(), putImageInv(), and getImage().  To use it
  487.                     with putHorizLine() and getHorizLine(), subtract 4 from
  488.                     the value it returns.  (Image buffers have four bytes
  489.                     of dimension information in them; line buffers do not.)
  490.      See also:      imageSize(), putImage(), putImageInv(), getImage(),
  491.                     putHorizLine(), getHorizLine()
  492.  
  493.  *** Function:      putHorizLine()
  494.      Syntax:        void putHorizLine(int y, int xOff, int lineLen, void
  495.                     far *buf);
  496.      Purpose:       Place one horizontal line of image data on the screen.
  497.      Parameters:    The one-line bitmap contained in 'buf', of 'lineLen'
  498.                     pixels, will be placed on-screen starting at
  499.                     ('xOff','y').
  500.      Return value:  None.
  501.      Remarks:       No clipping is performed.  Results are undefined if any
  502.                     coordinate on the line is off-screen.
  503.      See also:      putHorizLineInv(), getHorizLine(), putImage(),
  504.                     putImageInv(), getImage()
  505.  
  506.  *** Function:      putHorizLineInv()
  507.      Syntax:        void putHorizLineInv(int y, int xOff, int lineLen, void
  508.                     far *buf);
  509.      Purpose:       Place one horizontal line of image data on the screen,
  510.                     leaving a pixel unchanged if the corresponding pixel in
  511.                     the source buffer has a value of zero.
  512.      Parameters:    The one-line bitmap contained in 'buf', of 'lineLen'
  513.                     pixels, will be placed on-screen starting at
  514.                     ('xOff','y').
  515.      Return value:  None.
  516.      Remarks:       No clipping is performed.  Results are undefined if any
  517.                     coordinate on the line is off-screen.
  518.      See also:      putHorizLine(), getHorizLine(), putImage(),
  519.                     putImageInv(), getImage()
  520.  
  521.  *** Function:      getHorizLine()
  522.      Syntax:        void getHorizLine(int y, int xOff, int lineLen, void
  523.                     far *buf);
  524.      Purpose:       Copy one horizontal line from the screen to memory.
  525.      Parameters:    The horizontal line whose left coordinate is
  526.                     ('xOff','y') and whose length is 'lineLen' pixels will
  527.                     be copied into the previously allocated memory region
  528.                     at 'buf'.
  529.      Return value:  None.
  530.      Remarks:       No clipping is performed.  Results are undefined if any
  531.                     coordinate on the line is off-screen.
  532.      See also:      putHorizLine(), putHorizLineInv(), putImage(),
  533.                     putImageInv(), getImage()
  534.  
  535.  *** Function:      putVertLine()
  536.      Syntax:        void putVertLine(int y, int xOff, int lineLen, void far
  537.                     *buf);
  538.      Purpose:       Place one vertical line of image data on the screen.
  539.      Parameters:    The one-line bitmap contained in 'buf', of 'lineLen'
  540.                     pixels, will be placed on-screen starting at
  541.                     ('x','yOff').
  542.      Return value:  None.
  543.      Remarks:       No clipping is performed.  Results are undefined if any
  544.                     coordinate on the line is off-screen.
  545.      See also:      putVertLineInv(), getVertLine(), putImage(),
  546.                     putImageInv(), getImage()
  547.  
  548.  *** Function:      putVertLineInv()
  549.      Syntax:        void putVertLineInv(int y, int xOff, int lineLen, void
  550.                     far *buf);
  551.      Purpose:       Place one vertical line of image data on the screen,
  552.                     leaving a pixel unchanged if the corresponding pixel in
  553.                     the source buffer has a value of zero.
  554.      Parameters:    The one-line bitmap contained in 'buf', of 'lineLen'
  555.                     pixels, will be placed on-screen starting at
  556.                     ('x','yOff').
  557.      Return value:  None.
  558.      Remarks:       No clipping is performed.  Results are undefined if any
  559.                     coordinate on the line is off-screen.
  560.      See also:      putVertLine(), getVertLine(), putImage(),
  561.                     putImageInv(), getImage()
  562.  
  563.  *** Function:      getVertLine()
  564.      Syntax:        void getVertLine(int y, int xOff, int lineLen, void far
  565.                     *buf);
  566.      Purpose:       Copy one vertical line from the screen to memory.
  567.      Parameters:    The vertical line whose left coordinate is ('x','yOff')
  568.                     and whose length is 'lineLen' pixels will be copied
  569.                     into the previously allocated memory region at 'buf'.
  570.      Return value:  None.
  571.      Remarks:       No clipping is performed.  Results are undefined if any
  572.                     coordinate on the line is off-screen.
  573.      See also:      putVertLine(), putVertLineInv(), putImage(),
  574.                     putImageInv(), getImage()
  575.  
  576.  *** Function:      putPixel()
  577.      Syntax:        void putPixel(int x, int y, unsigned colour);
  578.      Purpose:       Place a single pixel on-screen.
  579.      Parameters:    The pixel located at ('x','y') will be set to the
  580.                     colour 'colour'.
  581.      Return value:  None.
  582.      Remarks:       Clipping is not performed; see clipPoint() and
  583.                     pointOnScreen() for details on clipping pixels.
  584.      See also:      getPixel()
  585.  
  586.  *** Function:      getPixel()
  587.      Syntax:        unsigned getPixel(int x, int y);
  588.      Purpose:       Return the value of a pixel.
  589.      Parameters:    The value of the pixel at ('x','y') is returned.
  590.      Return value:  The value of the pixel at ('x','y') is returned.
  591.      Remarks:       Clipping is not performed; see clipPoint() and
  592.                     pointOnScreen() for details on clipping pixels.
  593.      See also:      putPixel()
  594.  
  595.  *** Function:      line()
  596.      Syntax:        void line(int x1, int y1, int x2, int y2, unsigned
  597.                     colour);
  598.      Purpose:       Draw a line between two points.
  599.      Parameters:    The line will be drawn joining ('x1','y1') and
  600.                     ('x2','y2') in the colour 'colour'.
  601.      Return value:  None.
  602.      Remarks:       Clipping is not performed; see clipLine() for details
  603.                     on clipping lines.
  604.      See also:      horizLine(), vertLine()
  605.  
  606.  *** Function:      horizLine()
  607.      Syntax:        void horizLine(int y, int x1, int x2, unsigned colour);
  608.      Purpose:       Draw a horizontal line between two points.
  609.      Parameters:    The line will be drawn between ('x1','y') and
  610.                     ('x2','y') in the colour contained in colour.
  611.      Return value:  None.
  612.      Remarks:            Clipping is not performed.
  613.                          'x1' must be less than or equal to 'x2'.
  614.      See also:      vertLine(), line()
  615.  
  616.  *** Function:      vertLine()
  617.      Syntax:        void vertLine(int x, int y1, int y2, unsigned colour);
  618.      Purpose:       Draw a vertical line between two points.
  619.      Parameters:    The line will be drawn between ('x','y1') and
  620.                     ('x','y2') in the colour contained in colour.
  621.      Return value:  None.
  622.      Remarks:            Clipping is not performed.
  623.                          'y1' must be less than or equal to 'y2'.
  624.      See also:      horizLine(), line()
  625.  
  626.  *** Function:      drawRect()
  627.      Syntax:        void drawRect(int ulx, int uly, int lrx, int lry,
  628.                     unsigned colour);
  629.      Purpose:       Draw a rectangle.
  630.      Parameters:    The rectangle will be drawn with its upper-left
  631.                     coordinates at ('ulx','uly') and its lower-left
  632.                     coordinates at ('lrx','lry'), in the colour 'colour'.
  633.      Return value:  None.
  634.      Remarks:       Clipping is performed.
  635.      See also:      filledRect()
  636.  
  637.  *** Function:      filledRect()
  638.      Syntax:        void filledRect(int ulx, int uly, int lrx, int lry,
  639.                     unsigned colour);
  640.      Purpose:       Draw a filled rectangle.
  641.      Parameters:    The rectangle will be drawn with its upper-left
  642.                     coordinates at ('ulx','uly') and its lower-left
  643.                     coordinates at ('lrx','lry'), in the colour 'colour'.
  644.      Return value:  None.
  645.      Remarks:       Clipping is not performed; see clipFilledRect() for
  646.                     details on clipping filledRects.
  647.      See also:      drawRect()
  648.  
  649.  *** Function:      setPaletteReg()
  650.      Syntax:        void setPaletteReg(unsigned palReg, unsigned char red,
  651.                     unsigned char green, unsigned char blue);
  652.      Purpose:       Set a palette register.
  653.      Parameters:    The red, green, and blue components of the palette
  654.                     register palReg will be set to 'red', 'green', and
  655.                     'blue' respectively.
  656.      Return value:  None.
  657.      Remarks:       Each of the colour components ('red', 'green', 'blue')
  658.                     should be in the range 0..255, not 0..63 as would be
  659.                     the case using a stock VGA.  The drivers will take care
  660.                     of converting 8-bit to 6-bit palette resolution if
  661.                     necessary.
  662.      See also:      getPaletteReg(), setBlockPalette(), getBlockPalette()
  663.  
  664.  *** Function:      getPaletteReg()
  665.      Syntax:        void getPaletteReg(unsigned palReg, unsigned char far
  666.                     *red, unsigned char far *green, unsigned char far
  667.                     *blue);
  668.      Purpose:       Return the current settings of a palette register.
  669.      Parameters:    The red, green, and blue contents of the palette
  670.                     register palReg will be stored in 'red', 'green', and
  671.                     'blue' respectively.
  672.      Return value:  The red, green, and blue components of the palette
  673.                     register are returned in 'red', 'green', and 'blue'.
  674.      Remarks:       Each of the colour components ('red', 'green', 'blue')
  675.                     are in the range 0..255, not 0..63 as would be the case
  676.                     using a stock VGA card.  The drivers will take care of
  677.                     converting 8-bit to 6-bit palette resolution if
  678.                     necessary.
  679.      See also:      setPaletteReg(), setBlockPalette(), getBlockPalette()
  680.  
  681.  *** Function:      setBlockPalette()
  682.      Syntax:        void setBlockPalette(unsigned firstReg, unsigned
  683.                     lastReg, void far *data);
  684.      Purpose:       Set a block of palette registers.
  685.      Parameters:    The palette registers starting at 'firstReg' and ending
  686.                     at 'lastReg' will be set to the values contained in
  687.                     'data'.
  688.      Return value:  None.
  689.      Remarks:            The memory region at 'data' is organised in groups
  690.                     of three bytes; each group corresponds to one palette
  691.                     register, and each group is made up of, in order, the
  692.                     red, green, and blue components.  The first group is
  693.                     for the first register, the second for the second, and
  694.                     so on.
  695.                          Each of the colour components (red, green, blue)
  696.                     should be in the range 0..255, not 0..63 as would be
  697.                     the case using a stock VGA.  The drivers will take care
  698.                     of converting 8-bit to 6-bit palette resolution if
  699.                     necessary.
  700.                          Results are undefined if 'lastReg' is less than
  701.                     'firstReg'.
  702.      See also:      getBlockPalette(), setPaletteReg(), getPaletteReg()
  703.  
  704.  *** Function:      getBlockPalette()
  705.      Syntax:        void getBlockPalette(unsigned firstReg, unsigned
  706.                     lastReg, void far *data);
  707.      Purpose:       Get the values of a block of palette registers.
  708.      Parameters:    The values of the palette registers starting at
  709.                     'firstReg' and ending at 'lastReg' will be stored in
  710.                     the previously allocated 'data'.
  711.      Return value:  The values are returned in 'data'.
  712.      Remarks:            The memory region at 'data' is organised in groups
  713.                     of three bytes; each group corresponds to one palette
  714.                     register, and each group is made up of, in order, the
  715.                     red, green, and blue components.  The first group is
  716.                     for the first register, the second for the second, and
  717.                     so on.
  718.                          Each of the colour components (red, green, blue)
  719.                     is in the range 0..255, not 0..63 as would be the case
  720.                     using a stock VGA.  The drivers will take care of
  721.                     converting 8-bit to 6-bit palette resolution if
  722.                     necessary.
  723.                          Results are undefined if 'lastReg' is less than
  724.                     'firstReg'.
  725.      See also:      setBlockPalette(), setPaletteReg(), getPaletteReg()
  726.  
  727.  *** Function:      clearGraphics()
  728.      Syntax:        void clearGraphics(unsigned colour);
  729.      Purpose:       Clear the screen.
  730.      Parameters:    The screen will be cleared to the colour 'colour'.
  731.      Return value:  None.
  732.      Remarks:       This function clears the entire screen, not just the
  733.                     current viewport.
  734.      See also:      filledRect()
  735.  
  736.  *** Function:      ellipse()
  737.      Syntax:        void ellipse(int x, int y, int wide, int deep, unsigned
  738.                     colour);
  739.      Purpose:       Draw the outline of an ellipse.
  740.      Parameters:    An ellipse centered at ('x','y') and having width
  741.                     'wide' and depth 'deep' will be drawn in the colour
  742.                     'colour'.
  743.      Return value:  None.
  744.      Remarks:       Clipping is performed.
  745.      See also:      filledEllipse(), circle(), filledCircle()
  746.  
  747.  *** Function:      filledEllipse()
  748.      Syntax:        void filledEllipse(x, int y, int wide, int deep,
  749.                     unsigned colour);
  750.      Purpose:       Draw a filled ellipse.
  751.      Parameters:    An ellipse centered at ('x','y') and having width
  752.                     'wide' and depth 'deep' will be drawn in the colour
  753.                     'colour'.
  754.      Return value:  None.
  755.      Remarks:       Clipping is performed.
  756.      See also:      ellipse(), filledCircle(), circle()
  757.  
  758.  *** Function:      circle()
  759.      Syntax:        void circle(int x, int y, int radius, unsigned colour);
  760.      Purpose:       Draw the outline of a circle.
  761.      Parameters:    A circle centered at ('x','y') and having radius
  762.                     'radius' will be drawn in the colour 'colour'.
  763.      Return value:  None.
  764.      Remarks:            Clipping is performed.
  765.                          The 'radius' parameter is the radius in pixels
  766.                     measured horizontally.  Although there will be no
  767.                     difference in modes with square pixels, it will make a
  768.                     difference in other modes; to ensure accurate drawing
  769.                     of the circle with the given radius, make certain that
  770.                     the radius is measured horizontally.
  771.                          TGE uses an all-integer approach to coordinate
  772.                     scaling to ensure that the drawn shape will be circular
  773.                     in modes without square pixels.
  774.      See also:      filledCircle(), filledEllipse(), ellipse()
  775.  
  776.  *** Function:      filledCircle()
  777.      Syntax:        void filledCircle(int x, int y, int radius, unsigned
  778.                     colour);
  779.      Purpose:       Draw a filled circle.
  780.      Parameters:    A circle centered at ('x','y') and having radius
  781.                     'radius' will be drawn in the colour 'colour'.
  782.      Return value:  None.
  783.      Remarks:            Clipping is performed.
  784.                          The 'radius' parameter is the radius in pixels
  785.                     measured horizontally.  Although there will be no
  786.                     difference in modes with square pixels, it will make a
  787.                     difference in other modes; to ensure accurate drawing
  788.                     of the circle with the given radius, make certain that
  789.                     the radius is measured horizontally.
  790.                          TGE uses an all-integer approach to coordinate
  791.                     scaling to ensure that the drawn shape will be circular
  792.                     in modes without square pixels.
  793.      See also:      circle(), ellipse(), filledEllipse()
  794.  
  795.  *** Function:      fillRegion()
  796.      Syntax:        void fillRegion(int x, int y, unsigned colour);
  797.      Purpose:       Floods a region of the screen with the specified
  798.                     colour.
  799.      Parameters:    The fill will begin at the seed point ('x','y'), and
  800.                     will fill with the colour 'colour'.
  801.      Return value:  None.
  802.      Remarks:            The region to be filled is bounded by any colour
  803.                     not equal to the colour at ('x','y'); ie., the region
  804.                     to be filled consists of one colour only.
  805.                          Clipping is performed.
  806.      See also:      None.
  807.  
  808.  *** Function:      colourCloseTo()
  809.      Syntax:        unsigned colourCloseTo(unsigned char red, unsigned char
  810.                     green, unsigned char blue);
  811.      Purpose:       Given a 24-bit colour, find the colour from the current
  812.                     palette which most closely matches it.
  813.      Parameters:    The 24-bit colour is defined by the 'red', 'green', and
  814.                     'blue' parameters.
  815.      Return value:  Returns the colour which most closely matches the
  816.                     specified 24-bit colour.
  817.      Remarks:       None.
  818.      See also:      colourCloseToX()
  819.  
  820.  *** Function:      colourCloseToX()
  821.      Syntax:        unsigned colourCloseToX(unsigned char red, unsigned
  822.                     char green, unsigned char blue, unsigned
  823.                     colourExclude);
  824.      Purpose:       Given a 24-bit colour, find the colour from the current
  825.                     palette which most closely matches it, with the
  826.                     specified colour disallowed from the search.
  827.      Parameters:    The 24-bit colour is defined by the 'red', 'green', and
  828.                     'blue' parameters.  The colour 'colourExclude' is
  829.                     excluded from the search, and so will never be
  830.                     returned.
  831.      Return value:  Returns the colour which most closely matches the
  832.                     specified 24-bit colour.
  833.      Remarks:       Excluding zero from a search will ensure that the
  834.                     returned colour will be visible when it is used as part
  835.                     of a bitmap displayed using putImageInv().
  836.      See also:      colourCloseTo()
  837.  
  838.  
  839.      Note that since these function names are actually macros, they may
  840.      easily be changed to suit individual preferences by editing TGE.H.
  841.  
  842.  
  843.  
  844. VIEWPORTS AND CLIPPING
  845. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  846.  
  847.      A viewport is a rectangular region on the screen to which output is
  848.      clipped, so that graphics output will appear only within that region.
  849.      By default, this region is the entire screen; however, it can be set
  850.      to any rectangular portion of the screen.  (Note that when a viewport
  851.      is in use, coordinates are absolute, not relative to the viewport.)
  852.  
  853.      TGE now supports two viewports simultaneously:  an input viewport and
  854.      an output viewport.  This feature was added primarily so that virtual
  855.      screens (see the VIRTUAL SCREENS section) and the real screen could be
  856.      used simultaneously, though it may have other uses as well.  The
  857.      following functions are used to get and set the current input and
  858.      output viewports:
  859.  
  860.  *** Function:      setInputViewport()
  861.      Syntax:        void setInputViewport(int ulx, int uly, int lrx, int lry);
  862.      Purpose:       Set the defining coordinates of the current input
  863.                     viewport.
  864.      Parameters:    The upper-left corner of the input viewport will be set to
  865.                     ('ulx','uly'), and the lower-right corner to
  866.                     ('lrx','lry').
  867.      Return value:  None.
  868.      Remarks:       It is assumed that 'ulx'<'lrx' and that 'uly'<'lry'.
  869.      See also:      setOutputViewport(), setViewports(),
  870.                     getInputViewport(), getOutputViewport()
  871.  
  872.  *** Function:      setOutputViewport()
  873.      Syntax:        void setOutputViewport(int ulx, int uly, int lrx, int lry);
  874.      Purpose:       Set the defining coordinates of the current output
  875.                     viewport.
  876.      Parameters:    The upper-left corner of the output viewport will be set
  877.                     to ('ulx','uly'), and the lower-right corner to
  878.                     ('lrx','lry').
  879.      Return value:  None.
  880.      Remarks:       It is assumed that 'ulx'<'lrx' and that 'uly'<'lry'.
  881.      See also:      setInputViewport(), setViewports(),
  882.                     getOutputViewport(), getInputViewport()
  883.  
  884.  *** Function:      setViewports()
  885.      Syntax:        void setViewports(int ulx, int uly, int lrx, int lry);
  886.      Purpose:       Set the defining coordinates of the current input and
  887.                     output viewports.
  888.      Parameters:    The upper-left corner of the viewports will be set to
  889.                     ('ulx','uly'), and the lower-right corner to
  890.                     ('lrx','lry').
  891.      Return value:  None.
  892.      Remarks:       It is assumed that 'ulx'<'lrx' and that 'uly'<'lry'.
  893.      See also:      setInputViewport(), setOutputViewport(),
  894.                     getInputViewport(), getOutputViewport()
  895.  
  896.  *** Function:      getInputViewport()
  897.      Syntax:        void getInputViewport(int *ulx, int *uly, int *lrx, int
  898.                     *lry);
  899.      Purpose:       Get the defining coordinates of the current input
  900.                     viewport.
  901.      Parameters:    The upper-left corner of the input viewport will be stored
  902.                     in ('ulx','uly'), and the lower-right corner in
  903.                     ('lrx','lry').
  904.      Return value:  None.
  905.      Remarks:       It is assumed that 'ulx'<'lrx' and that 'uly'<'lry'.
  906.      See also:      getOutputViewport(), setInputViewport(),
  907.                     setOutputViewport()
  908.  
  909.  *** Function:      getOutputViewport()
  910.      Syntax:        void getOutputViewport(int *ulx, int *uly, int *lrx, int
  911.                     *lry);
  912.      Purpose:       Get the defining coordinates of the current output
  913.                     viewport.
  914.      Parameters:    The upper-left corner of the output viewport will be
  915.                     stored in ('ulx','uly'), and the lower-right corner in
  916.                     ('lrx','lry').
  917.      Return value:  None.
  918.      Remarks:       It is assumed that 'ulx'<'lrx' and that 'uly'<'lry'.
  919.      See also:      setOutputViewport(), getInputViewport(),
  920.                     getOutputViewport()
  921.  
  922.  
  923.      Note that not all of TGE's functions will clip to within the current
  924.      output viewport.  Some of the time-critical graphics primitives, such
  925.      as putPixel() and line(), do not clip in order to improve execution
  926.      time.  If it is necessary for such functions to have their output
  927.      clipped, the following routines may be used:
  928.  
  929.  *** Function:      clipRect()
  930.      Syntax:        int clipRect(int *x1, int *y1, int *x2, int *y2);
  931.      Purpose:       Clip the given rectangle to within the current output
  932.                     viewport.
  933.      Parameters:    The upper-left and lower-right corners of the rectangle
  934.                     are passed in ('x1','y1') and ('x2','y2').  If clipping
  935.                     is done, these points will be modified.
  936.      Return value:  Returns true if the rectangle lies entirely or
  937.                     partially within the current output viewport, or false
  938.                     if it is entirely outside the current output viewport.
  939.      Remarks:            It does not matter which of the corner coordinates
  940.                     is passed first; they will be swapped if necessary.
  941.                          This function is contained in CLIP.C.
  942.  
  943.  *** Function:      clipLine()
  944.      Syntax:        int clipLine(int *x1, int *y1, int *x2, int *y2);
  945.      Purpose:       Clip the given line to within the current output
  946.                     viewport.
  947.      Parameters:    The endpoints of the line are passed in ('x1','y1') and
  948.                     ('x2','y2').  If clipping is done, these endpoints will
  949.                     be modified.
  950.      Return value:  Returns true if the line lies entirely or partially
  951.                     within the current output viewport, or false if it is
  952.                     entirely outside the current output viewport.
  953.      Remarks:       This function is contained in CLIP.C.
  954.      See also:      None.
  955.  
  956.  *** Function:      clipInputPoint()
  957.      Syntax:        int clipInputPoint(int x, int y);
  958.      Purpose:       Return a flag indicating whether or not the specified
  959.                     coordinates lie within the current input viewport.
  960.      Parameters:    The point ('x','y') is tested.
  961.      Return value:  Returns true if ('x','y') is within the current
  962.                     input viewport, or 0 if it isn't.
  963.      Remarks:       This function is really a macro defined in TGE.H.
  964.      See also:      None.
  965.  
  966.  *** Function:      clipOutputPoint()
  967.      Syntax:        int clipOutputPoint(int x, int y);
  968.      Purpose:       Return a flag indicating whether or not the specified
  969.                     coordinates lie within the current output viewport.
  970.      Parameters:    The point ('x','y') is tested.
  971.      Return value:  Returns true if ('x','y') is within the current
  972.                     output viewport, or 0 if it isn't.
  973.      Remarks:       This function is really a macro defined in TGE.H.
  974.      See also:      None.
  975.  
  976.  *** Function:      pointOnScreen()
  977.      Syntax:        int pointOnScreen(int x, int y);
  978.      Purpose:       Return a flag indicating whether or not the specified
  979.                     coordinates lie on-screen.
  980.      Parameters:    The point ('x','y') is tested.
  981.      Return value:  Returns true if ('x','y') is on-screen, or 0 if it is
  982.                     off-screen.
  983.      Remarks:       This function is really a macro defined in TGE.H.
  984.      See also:      None.
  985.  
  986.  
  987.      Note that since these function names are actually macros, they may
  988.      easily be changed to suit individual preferences by editing TGE.H.
  989.  
  990.  
  991.  
  992. VIRTUAL COORDINATES
  993. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  994.  
  995.      One of the problems associated with device-independence is that
  996.      different display modes have different resolutions.  TGE provides a
  997.      simple way to ease this problem, simply by #including VCOORD.H.  Doing
  998.      so provides access to a simple yet powerful object-oriented virtual
  999.      coordinate system.
  1000.  
  1001.      For the sake of illustration, assume that you are writing an
  1002.      application which ideally will be run in resolutions as high as
  1003.      1024x768, but can also be run in 320x200.  You want a way to have
  1004.      objects (eg., windows) retain the same sizes and positions on-screen
  1005.      in any graphics mode.  TGE's virtual coordinate system makes it easy.
  1006.      First, create an instance of the virtual coordinate object (I'll call
  1007.      the object virtScreen):
  1008.  
  1009.           VirtualCoord virtScreen;
  1010.  
  1011.      Then, virtScreen must be configured; I'll assume that the virtual
  1012.      screen is to be 1024x768, and that OUTMAXX and OUTMAXY have been
  1013.      initialized by loading a driver.  (Note that these parameters may be
  1014.      set during the class instantiation by using a different constructor.)
  1015.  
  1016.           virtScreen.virtParams(1023, 767);
  1017.           virtScreen.realParams(OUTMAXX, OUTMAXY);
  1018.  
  1019.      As an example, assume that you want to draw a light gray rectangle
  1020.      with upper-left coordinates (50,50) and lower-right coordinates
  1021.      (600,600) on the virtual screen.  On, say, a 360x480 screen these
  1022.      values will be quite different; to keep the proportions the same,
  1023.      execute a line like the following:
  1024.  
  1025.           drawRect(virtScreen.realX(50), virtScreen.realY(50),
  1026.                    virtScreen.realX(600), virtScreen.realY(600),
  1027.                    colourCloseTo(200,200,200));
  1028.  
  1029.      That's all there is to it!  Keep in mind that there are other
  1030.      applications of the VirtualCoord class, aside from a virtual screen;
  1031.      it can also be useful when dealing with portions of the screen, scaled
  1032.      bitmaps, etc..
  1033.  
  1034.      A complete list of the VirtualCoord member functions follows.
  1035.  
  1036.  
  1037.  *** Function:      VirtualCoord::VirtualCoord()
  1038.      Syntax:        VirtualCoord::VirtualCoord(void);
  1039.      Purpose:       Create an instance of the VirtualCoord class.
  1040.      Parameters:    None.
  1041.      Return value:  None.
  1042.      Remarks:       After an instantiation of a VirtualCoord using this
  1043.                     constructor, ensure that the screen dimensions, both
  1044.                     virtual and real, are initialized using the method
  1045.                     illustrated above.
  1046.      See also:      VirtualCoord::VirtualCoord(unsigned, unsigned,
  1047.                     unsigned, unsigned), VirtualCoord::virtParams(unsigned,
  1048.                     unsigned), VirtualCoord::realParams(unsigned, unsigned)
  1049.  
  1050.  *** Function:      VirtualCoord::VirtualCoord(unsigned, unsigned,
  1051.                     unsigned, unsigned)
  1052.      Syntax:        VirtualCoord::VirtualCoord(unsigned virtMaxX, unsigned
  1053.                     virtMaxY, unsigned realMaxX, unsigned realMaxY);
  1054.      Purpose:       Create an instance of the VirtualCoord class, and
  1055.                     initialize it.
  1056.      Parameters:    The maximum virtual x-coordinate is set to 'virtMaxX',
  1057.                     and the y-coordinate to 'virtMaxY'.  The maximum real
  1058.                     x-coordinate is set to 'realMaxX', and the y-coordinate
  1059.                     to 'realMaxY'.
  1060.      Return value:  None.
  1061.      Remarks:       Be sure that a driver has been loaded before passing
  1062.                     OUTMAXX and OUTMAXY to this constructor.
  1063.      See also:      VirtualCoord::VirtualCoord(unsigned, unsigned,
  1064.                     unsigned, unsigned), VirtualCoord::virtParams(unsigned,
  1065.                     unsigned), VirtualCoord::realParams(unsigned, unsigned)
  1066.  
  1067.  *** Function:      VirtualCoord::virtParams(unsigned, unsigned)
  1068.      Syntax:        void VirtualCoord::virtParams(unsigned virtMaxX,
  1069.                     unsigned virtMaxY);
  1070.      Purpose:       Set the maximum virtual x- and y-coordinates.
  1071.      Parameters:    The maximum virtual x-coordinate is set to 'virtMaxX',
  1072.                     and the maximum y-coordinate to 'virtMaxY'.
  1073.      Return value:  None.
  1074.      Remarks:       None.
  1075.      See also:      VirtualCoord::realParams(unsigned, unsigned),
  1076.                     VirtualCoord::virtParams(unsigned*, unsigned*),
  1077.                     VirtualCoord::realParams(unsigned*, unsigned*)
  1078.  
  1079.  *** Function:      VirtualCoord::realParams(unsigned, unsigned)
  1080.      Syntax:        void VirtualCoord::realParams(unsigned virtMaxX,
  1081.                     unsigned virtMaxY);
  1082.      Purpose:       Set the maximum real x- and y-coordinates.
  1083.      Parameters:    The maximum real x-coordinate is set to 'realMaxX', and
  1084.                     the maximum y-coordinate to 'realMaxY'.
  1085.      Return value:  None.
  1086.      Remarks:       None.
  1087.      See also:      VirtualCoord::virtParams(unsigned, unsigned),
  1088.                     VirtualCoord::realParams(unsigned*, unsigned*),
  1089.                     VirtualCoord::virtParams(unsigned*, unsigned*)
  1090.  
  1091.  *** Function:      VirtualCoord::virtParams(unsigned*, unsigned*)
  1092.      Syntax:        void VirtualCoord::virtParams(unsigned *virtMaxX,
  1093.                     unsigned *virtMaxY);
  1094.      Purpose:       Get the maximum virtual x- and y-coordinates.
  1095.      Parameters:    The maximum virtual x-coordinate is stored in
  1096.                     'virtMaxX', and the maximum y-coordinate in 'virtMaxY'.
  1097.      Return value:  None.
  1098.      Remarks:       None.
  1099.      See also:      VirtualCoord::realParams(unsigned*, unsigned*),
  1100.                     VirtualCoord::virtParams(unsigned, unsigned),
  1101.                     VirtualCoord::realParams(unsigned, unsigned)
  1102.  
  1103.  *** Function:      VirtualCoord::realParams(unsigned*, unsigned*)
  1104.      Syntax:        void VirtualCoord::realParams(unsigned *virtMaxX,
  1105.                     unsigned *virtMaxY);
  1106.      Purpose:       Get the maximum real x- and y-coordinates.
  1107.      Parameters:    The maximum real x-coordinate is stored in 'realMaxX',
  1108.                     and the maximum y-coordinate in 'realMaxY'.
  1109.      Return value:  None.
  1110.      Remarks:       None.
  1111.      See also:      VirtualCoord::virtParams(unsigned*, unsigned*),
  1112.                     VirtualCoord::realParams(unsigned, unsigned),
  1113.                     VirtualCoord::virtParams(unsigned, unsigned)
  1114.  
  1115.  *** Function:      VirtualCoord::realCoords()
  1116.      Syntax:        void VirtualCoord::realCoords(unsigned virtX, unsigned
  1117.                     virtY, unsigned *realX, unsigned *realY);
  1118.      Purpose:       Calculate the real (x,y) coordinates given the virtual
  1119.                     coordinates.
  1120.      Parameters:    The real (x,y) coordinates are returned in
  1121.                     ('realX','realY'), and are calculated based on the
  1122.                     virtual (x,y) coordinates ('virtX','virtY').
  1123.      Return value:  None.
  1124.      Remarks:       None.
  1125.      See also:      VirtualCoord::realX(), VirtualCoord::realY(),
  1126.                     VirtualCoord::virtCoords(), VirtualCoord::virtX(),
  1127.                     VirtualCoord::virtY()
  1128.  
  1129.  *** Function:      VirtualCoord::realX()
  1130.      Syntax:        unsigned VirtualCoord::realX(unsigned virtX);
  1131.      Purpose:       Calculate the real x-coordinate given the virtual x-
  1132.                     coordinate.
  1133.      Parameters:    The real x-coordinate is returned, calculated based on
  1134.                     the virtual x-coordinate 'virtX'.
  1135.      Return value:  Returns the real x-coordinate.
  1136.      Remarks:       None.
  1137.      See also:      VirtualCoord::realY(), VirtualCoord::realCoords(),
  1138.                     VirtualCoord::virtX(), VirtualCoord::virtY(),
  1139.                     VirtualCoord::virtCoords()
  1140.  
  1141.  *** Function:      VirtualCoord::realY()
  1142.      Syntax:        unsigned VirtualCoord::realY(unsigned virtY);
  1143.      Purpose:       Calculate the real y-coordinate given the virtual y-
  1144.                     coordinate.
  1145.      Parameters:    The real y-coordinate is returned, calculated based on
  1146.                     the virtual y-coordinate 'virtY'.
  1147.      Return value:  Returns the real y-coordinate.
  1148.      Remarks:       None.
  1149.      See also:      VirtualCoord::realX(), VirtualCoord::realCoords(),
  1150.                     VirtualCoord::virtY(), VirtualCoord::virtX(),
  1151.                     VirtualCoord::virtCoords()
  1152.  
  1153.  *** Function:      VirtualCoord::virtCoords()
  1154.      Syntax:        void VirtualCoord::virtCoords(unsigned realX, unsigned
  1155.                     realY, unsigned *virtX, unsigned *virtY);
  1156.      Purpose:       Calculate the virtual (x,y) coordinates given the real
  1157.                     coordinates.
  1158.      Parameters:    The virtual (x,y) coordinates are returned in
  1159.                     ('virtX','virtY'), and are calculated based on the real
  1160.                     (x,y) coordinate ('realX','realY').
  1161.      Return value:  None.
  1162.      Remarks:       None.
  1163.      See also:      VirtualCoord::virtX(), VirtualCoord::virtY(),
  1164.                     VirtualCoord::realCoords(), VirtualCoord::realX(),
  1165.                     VirtualCoord::realY()
  1166.  
  1167.  *** Function:      VirtualCoord::virtX()
  1168.      Syntax:        unsigned VirtualCoord::virtX(unsigned realX);
  1169.      Purpose:       Calculate the virtual x-coordinate given the real x-
  1170.                     coordinate.
  1171.      Parameters:    The virtual x-coordinate is returned, calculated based
  1172.                     on the real x-coordinate 'realX'.
  1173.      Return value:  Returns the virtual x-coordinate.
  1174.      Remarks:       None.
  1175.      See also:      VirtualCoord::virtY(), VirtualCoord::virtCoords(),
  1176.                     VirtualCoord::realX(), VirtualCoord::realY(),
  1177.                     VirtualCoord::realCoords()
  1178.  
  1179.  *** Function:      VirtualCoord::virtY()
  1180.      Syntax:        unsigned VirtualCoord::virtY(unsigned realY);
  1181.      Purpose:       Calculate the virtual y-coordinate given the real y-
  1182.                     coordinate.
  1183.      Parameters:    The virtual y-coordinate is returned, calculated based
  1184.                     on the real y-coordinate 'realY'.
  1185.      Return value:  Returns the virtual y-coordinate.
  1186.      Remarks:       None.
  1187.      See also:      VirtualCoord::virtX(), VirtualCoord::virtCoords(),
  1188.                     VirtualCoord::realY(), VirtualCoord::realX(),
  1189.                     VirtualCoord::realCoords()
  1190.  
  1191.  
  1192.  
  1193. VIRTUAL SCREENS
  1194. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1195.  
  1196.      In early releases of TGE, all graphics input and output operations
  1197.      were done on the screen.  Now four different I/O arrangements are
  1198.      available:
  1199.         - Input and output on the real screen.
  1200.         - Input and output on a virtual screen (ie. in memory).
  1201.         - Input from the real screen, and output to a virtual screen.
  1202.         - Input from a virtual screen, and output to the real screen.
  1203.      As well, it is possible to switch between these four I/O modes at any
  1204.      time with one or two simple function calls.
  1205.  
  1206.      Virtual screens are useful for such tasks as building complex images
  1207.      off-screen, then displaying them quickly.  Since a virtual screen has
  1208.      exactly the same format as the images used by getImage() and its
  1209.      associated functions, they can be displayed using a putImage() or
  1210.      putImageInv() call, simply by passing the address of the virtual
  1211.      screen as the address of the image to be displayed.
  1212.  
  1213.  
  1214.      A virtual screen (or any bitmap, for that matter) may be created using
  1215.      the following function:
  1216.  
  1217.  *** Function:      makeVirtScreen()
  1218.      Syntax:        void far *makeVirtScreen(unsigned wide, unsigned deep);
  1219.      Purpose:       Allocate enough RAM to store a virtual screen with the
  1220.                     specified dimensions, then initialize it.
  1221.      Parameters:    A virtual screen with width 'wide' and depth 'deep' (in
  1222.                     pixels) will be created.
  1223.      Return value:  Returns the address of the newly allocated virtual
  1224.                     screen, or NULL if there is not enough memory to create
  1225.                     it.
  1226.      Remarks:            Memory for the virtual screen is alloated from
  1227.                     available conventional memory; don't forget to
  1228.                     de-allocate (using farfree()) the memory occupied by a
  1229.                     virtual screen when the screen is no longer needed.
  1230.                          After it is allocated, a virtual screen will
  1231.                     likely be filled with random pixels.  Clearing it using
  1232.                     clearGraphics() is often a good idea (after graphics
  1233.                     output has been set to the virtual screen).
  1234.      See also:      None.
  1235.      
  1236.  
  1237.      The functions used to establish input and output to and from real and
  1238.      virtual screens are:
  1239.  
  1240.  *** Function:      setGraphicsAddr()
  1241.      Syntax:        void setGraphicsAddr(void far *addr);
  1242.      Purpose:       Set the location upon which graphics input and output
  1243.                     will both be performed.
  1244.      Parameters:    If 'addr' is equal to NULL, input and output will be
  1245.                     performed on the real screen; if 'addr' is non-NULL,
  1246.                     input and output will be performed on the virtual
  1247.                     screen pointed to by 'addr'.
  1248.      Return value:  None.
  1249.      Remarks:       This function sets the currently active input and
  1250.                     output viewports to cover the entirety of the virtual
  1251.                     screen.  INMAXX, INMAXY, OUTMAXX, and OUTMAXY are also
  1252.                     changed appropriately.
  1253.      See also:      setGraphicsInputAddr(), setGraphicsOutputAddr()
  1254.  
  1255.  *** Function:      setGraphicsInputAddr()
  1256.      Syntax:        void setGraphicsInputAddr(void far *addr);
  1257.      Purpose:       Set the location upon which graphics input will be
  1258.                     performed.
  1259.      Parameters:    If 'addr' is equal to NULL, input will be performed on
  1260.                     the real screen; if 'addr' is non-NULL, input will be
  1261.                     performed on the virtual screen pointed to by 'addr'.
  1262.      Return value:  None.
  1263.      Remarks:       This function sets the currently active input viewport
  1264.                     to cover the entirety of the virtual screen.  INMAXX
  1265.                     and INMAXY are also changed appropriately.
  1266.      See also:      setGraphicsOutputAddr(), setGraphicsAddr()
  1267.  
  1268.  *** Function:      setGraphicsOutputAddr()
  1269.      Syntax:        void setGraphicsOutputAddr(void far *addr);
  1270.      Purpose:       Set the location upon which graphics output will be
  1271.                     performed.
  1272.      Parameters:    If 'addr' is equal to NULL, output will be performed on
  1273.                     the real screen; if 'addr' is non-NULL, output will be
  1274.                     performed on the virtual screen pointed to by 'addr'.
  1275.      Return value:  None.
  1276.      Remarks:       This function sets the currently active output viewport
  1277.                     to cover the entirety of the virtual screen.  OUTMAXX
  1278.                     and OUTMAXY are also changed appropriately.
  1279.      See also:      setGraphicsInputAddr(), setGraphicsAddr()
  1280.  
  1281.  *** Function:      getGraphicsInputAddr()
  1282.      Syntax:        void far *getGraphicsInputAddr(void);
  1283.      Purpose:       Get the location upon which graphics input is currently
  1284.                     being performed.
  1285.      Parameters:    None.
  1286.      Return value:  Returns NULL if graphics input is currently being
  1287.                     performed on the physical screen, or the address of the
  1288.                     virtual screen upon which input is being performed
  1289.                     otherwise.
  1290.      Remarks:       None.
  1291.      See also:      getGraphicsOutputAddr()
  1292.  
  1293.  *** Function:      getGraphicsOutputAddr()
  1294.      Syntax:        void far *getGraphicsOutputAddr(void);
  1295.      Purpose:       Get the location upon which graphics output is currently
  1296.                     being performed.
  1297.      Parameters:    None.
  1298.      Return value:  Returns NULL if graphics output is currently being
  1299.                     performed on the physical screen, or the address of the
  1300.                     virtual screen upon which output is being performed
  1301.                     otherwise.
  1302.      Remarks:       None.
  1303.      See also:      getGraphicsInputAddr()
  1304.  
  1305.  
  1306.  
  1307. GRAPHICAL OUTPUT MODES
  1308. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1309.  
  1310.      In early releases of TGE, all graphics output was copied to the
  1311.      screen.  Now output can be copied, ANDed, NOTed, ORed, or XORed, even
  1312.      to virtual screens.  A description of each of these output modes
  1313.      follows:
  1314.         - COPY:  This mode is the one which will likely be used most
  1315.           frequently.  In this mode, any output is copied directly,
  1316.           overwriting anything which was previously there.
  1317.         - AND:  In this mode, each pixel output is ANDed with the pixel
  1318.           already at the same location.
  1319.         - NOT:  In this mode, each pixel output is NOTed before being
  1320.           output.
  1321.         - OR:  In this mode, each pixel output is ORed with the pixel
  1322.           already at the same location.
  1323.         - XOR:  In this mode, each pixel output is XORed with the pixel
  1324.           already at the same location.
  1325.  
  1326.  
  1327.      The following function allows selection of the output mode:
  1328.  
  1329.  *** Function:      setGraphicsOutputMode()
  1330.      Syntax:        void setGraphicsOutputMode(int mode);
  1331.      Purpose:       Select the currently used output mode.
  1332.      Parameters:    The output mode will be set to COPY if 'mode' is
  1333.                     TGE_COPY_PUT, AND if it is TGE_AND_PUT, NOT if it is
  1334.                     TGE_NOT_PUT, OR if it is TGE_OR_PUT, or XOR if it is
  1335.                     TGE_XOR_PUT.  These macros are defined in TGE.H.
  1336.      Return value:  None.
  1337.      Remarks:       These output modes affect output to physical and
  1338.                     virtual screens.
  1339.      See also:      None.
  1340.  
  1341.  
  1342.  
  1343. USING FONTS
  1344. ▀▀▀▀▀▀▀▀▀▀▀
  1345.  
  1346.      TGE supports two types of loadable fonts:  fixed-size monochrome fonts
  1347.      (implemented with the FixedFont class), and variable-size 256-colour
  1348.      fonts (implemented with the VariableFont class).  Both high- and
  1349.      low-ASCII characters are supported.  As well, multiple fonts may be
  1350.      resident in memory simultaneously.
  1351.  
  1352.      For variable-size 256-colour fonts:
  1353.      ──────────────────────────────────
  1354.           Before attempting to use variable-size fonts, it is a good idea
  1355.           to understand exactly what it is that is variable.  Variable-size
  1356.           fonts DO NOT, at present, have the capability of scaling their
  1357.           member functions to arbitrary sizes.  What is meant by variable
  1358.           is that the character bitmaps themselves, while not resizable,
  1359.           are not all of the same size; eg., the letter 'm' is shorter and
  1360.           wider than the letter 'l', but neither can be resized.
  1361.  
  1362.           In order to use a variable-size 256-colour font, an instance of
  1363.           the VariableFont class is necessary.  Font initialization will
  1364.           look something like this:
  1365.  
  1366.                VariableFont systemFont;
  1367.                char systemFontName[] = "BIGTEXT";
  1368.                     .
  1369.                     .
  1370.                     .
  1371.                if (!systemFont.load(systemFontName))
  1372.                {
  1373.                  printf("Error loading %s; aborting.\n\n", systemFontName);
  1374.                  exit(EXIT_FAILURE);
  1375.                }
  1376.  
  1377.           Once a font has been loaded, it may be manipulated via its
  1378.           VariableFont class instance.  The class destructor automatically
  1379.           removes the font from memory.
  1380.  
  1381.           A complete list of the VariableFont member functions follows.
  1382.  
  1383.  
  1384.       *** Function:      VariableFont::load()
  1385.           Syntax:        int VariableFont::load(char *filename);
  1386.           Purpose:       Load a font from disk.
  1387.           Parameters:    The font file 'filename' will be loaded.
  1388.           Return value:  Returns 0 on error.
  1389.           Remarks:       None.
  1390.           See also:      None.
  1391.  
  1392.       *** Function:      VariableFont::put()
  1393.           Syntax:        void VariableFont::put(int x, int y, char
  1394.                          ch);
  1395.           Purpose:       Write a character on screen.
  1396.           Parameters:    The character 'ch' will be displayed with its
  1397.                          upper-left corner at ('x','y').
  1398.           Return value:  None.
  1399.           Remarks:       None.
  1400.           See also:      VariableFont::put(int, int, char*)
  1401.  
  1402.       *** Function:      VariableFont::put()
  1403.           Syntax:        void VariableFont::put(int x, int y, char
  1404.                          *string);
  1405.           Purpose:       Write a string on screen.
  1406.           Parameters:    The string 'string' will be displayed with its
  1407.                          upper-left corner at ('x','y').
  1408.           Return value:  None.
  1409.           Remarks:       None.
  1410.           See also:      VariableFont::put(int, int, char)
  1411.  
  1412.       *** Function:      VariableFont::width()
  1413.           Syntax:        unsigned VariableFont::width(char *string);
  1414.           Purpose:       Determine the width of a string.
  1415.           Parameters:    The width of the string 'string' will be
  1416.                          determined.
  1417.           Return value:  The width of the string, in pixels, will be
  1418.                          returned.
  1419.           Remarks:       None.
  1420.           See also:      VariableFont::width(char),
  1421.                          VariableFont::height(char*),
  1422.                          VariableFont::height(char)
  1423.  
  1424.       *** Function:      VariableFont::height()
  1425.           Syntax:        unsigned VariableFont::height(char *string);
  1426.           Purpose:       Determine the height of a string.
  1427.           Parameters:    The height of the string 'string' will be
  1428.                          determined.
  1429.           Return value:  The height of the string, in pixels, will be
  1430.                          returned.
  1431.           Remarks:       None.
  1432.           See also:      VariableFont::height(char),
  1433.                          VariableFont::width(char*),
  1434.                          VariableFont::width(char),
  1435.                          VariableFont::maxHeight()
  1436.  
  1437.       *** Function:      VariableFont::width()
  1438.           Syntax:        unsigned short VariableFont::width(char ch);
  1439.           Purpose:       Determine the width of a character.
  1440.           Parameters:    The width of the character 'ch' will be
  1441.                          determined.
  1442.           Return value:  The width of the string, in pixels, will be
  1443.                          returned.
  1444.           Remarks:       None.
  1445.           See also:      VariableFont::width(char*),
  1446.                          VariableFont::height(char),
  1447.                          VariableFont::width(char*)
  1448.  
  1449.       *** Function:      VariableFont::height()
  1450.           Syntax:        unsigned short VariableFont::height(char ch);
  1451.           Purpose:       Determine the height of a character.
  1452.           Parameters:    The height of the character 'ch' will be
  1453.                          determined.
  1454.           Return value:  The height of the string, in pixels, will be
  1455.                          returned.
  1456.           Remarks:       None.
  1457.           See also:      VariableFont::height(char*),
  1458.                          VariableFont::width(char),
  1459.                          VariableFont::height(char*),
  1460.                          VariableFont::maxHeight()
  1461.  
  1462.       *** Function:      VariableFont::maxHeight()
  1463.           Syntax:        unsigned short VariableFont::maxHeight(void);
  1464.           Purpose:       Determine the height of the tallest character.
  1465.           Parameters:    None.
  1466.           Return value:  The height of the tallest character, in pixels,
  1467.                          will be returned.
  1468.           Remarks:       None.
  1469.           See also:      VariableFont::height(char*),
  1470.                          VariableFont::height(char)
  1471.  
  1472.       *** Function:      VariableFont::matchColours()
  1473.           Syntax:        void VariableFont::matchColours(void);
  1474.           Purpose:       Match the font colours as closely as possible to
  1475.                          the currently selected font palette.
  1476.           Parameters:    None.
  1477.           Return value:  None.
  1478.           Remarks:       This function is really only useful after the
  1479.                          colour palette has been changed.
  1480.           See also:      VariableFont::palette(void*)
  1481.  
  1482.       *** Function:      VariableFont::palette(void*)
  1483.           Syntax:        void VariableFont::palette(void *palette);
  1484.           Purpose:       Change the currently active font palette.
  1485.           Parameters:    The currently active font palette will be set to
  1486.                          the palette at 'palette'.
  1487.           Return value:  None.
  1488.           Remarks:       VariableFont::matchColours() is autmatically
  1489.                          called by this function.
  1490.           See also:      VariableFont::palette(void),
  1491.                          VariableFont::palette(unsigned char, unsigned
  1492.                          char, unsigned char, unsigned char),
  1493.                          VariableFont::matchColours()
  1494.  
  1495.       *** Function:      VariableFont::palette(void)
  1496.           Syntax:        void *VariableFont::palette(void);
  1497.           Purpose:       Get the address of the currently active font
  1498.                          palette.
  1499.           Parameters:    None.
  1500.           Return value:  Returns the address of the font palette.
  1501.           Remarks:       If a change is made to this data directly, you
  1502.                          must call VariableFont::palette(void*) if the
  1503.                          changes are to take effect.
  1504.           See also:      VariableFont::palette(void),
  1505.                          VariableFont::palette(unsigned char, unsigned
  1506.                          char*, unsigned char*, unsigned char*)
  1507.  
  1508.       *** Function:      VariableFont::palette(unsigned char, unsigned
  1509.                          char, unsigned char, unsigned char)
  1510.           Syntax:        void VariableFont::palette(unsigned char palReg,
  1511.                          unsigned char red, unsigned char green, unsigned
  1512.                          char blue);
  1513.           Purpose:       Change one of the colours of the font palette.
  1514.           Parameters:    Colour number 'palReg' of the font palette will be
  1515.                          set to match the values passed in 'red', 'green',
  1516.                          and 'blue'.
  1517.           Return value:  None.
  1518.           Remarks:       The change will take effect immediately; there is
  1519.                          no need to explicitly update the palette.
  1520.           See also:      VariableFont::palette(void*)
  1521.  
  1522.       *** Function:      VariableFont::palette(unsigned char, unsigned
  1523.                          char*, unsigned char*, unsigned char*)
  1524.           Syntax:        void VariableFont::palette(unsigned char palReg,
  1525.                          unsigned char *red, unsigned char *green, unsigned
  1526.                          char *blue);
  1527.           Purpose:       Determine the contents of one of the colours of
  1528.                          the font palette.
  1529.           Parameters:    Colour number 'palReg' of the font palette will be
  1530.                          passed to the caller in 'red', 'green', and
  1531.                          'blue'.
  1532.           Return value:  None.  On return, however, the colour's components
  1533.                          will be present at the 'red', 'green', and 'blue'
  1534.                          buffers.
  1535.           Remarks:       None.
  1536.           See also:      VariableFont::palette(void)
  1537.  
  1538.       *** Function:      VariableFont::spacing()
  1539.           Syntax:        void VariableFont::spacing(unsigned numPixels);
  1540.           Purpose:       Change the spacing between characters.
  1541.           Parameters:    After calling this function, the number of pixels
  1542.                          left between characters output with
  1543.                          VariableFont::put(char*) will be set to
  1544.                          'numPixels'.
  1545.           Return value:  None.
  1546.           Remarks:       The spacing defaults to one pixel between each
  1547.                          character.
  1548.           See also:      VariableFont::spacing(void)
  1549.  
  1550.       *** Function:      VariableFont::spacing()
  1551.           Syntax:        unsigned VariableFont::spacing(void);
  1552.           Purpose:       Return the spacing between characters.
  1553.           Parameters:    None.
  1554.           Return value:  Returns the number of pixels used to space two
  1555.                          adjacent characters.
  1556.           Remarks:       The spacing defaults to one pixel between each
  1557.                          character.
  1558.           See also:      VariableFont::spacing(unsigned)
  1559.  
  1560.  
  1561.  
  1562.      For fixed-size monochrome fonts:
  1563.      ───────────────────────────────
  1564.           In order to use a fixed-size monochrome font, an instance of the
  1565.           FixedFont class is necessary.  Assuming instantiation of a
  1566.           FixedFont pointer, font initialization will look something like
  1567.           this:
  1568.  
  1569.                FixedFont fixedFont;
  1570.                char fixedFontName[] = "8X16";
  1571.                          .
  1572.                          .
  1573.                          .
  1574.                if (!fixedFont.load(fixedFontName))
  1575.                {
  1576.                  printf("Error loading %s; aborting.\n\n", fixedFontName);
  1577.                  exit(EXIT_FAILURE);
  1578.                }
  1579.  
  1580.           Once a font has been loaded, it may be manipulated via its
  1581.           FixedFont class instance.  The class destructor automatically
  1582.           removes the font from memory.
  1583.  
  1584.           A complete list of the FixedFont member functions follows.
  1585.  
  1586.       *** Function:      FixedFont::FixedFont()
  1587.           Syntax:        FixedFont::FixedFont(unsigned char fg=1, unsigned
  1588.                          char bg=0);
  1589.           Purpose:       Initiate a FixedFont class for use with a font
  1590.                          which will be loaded later.
  1591.           Parameters:    'fg' (which defaults to 1) is the colour to be
  1592.                          used as the foreground colour.  'bg' (which
  1593.                          defaults to 0) is the colour to be used as the
  1594.                          background colour.
  1595.           Return value:  None.
  1596.           Remarks:       None.
  1597.           See also:      None.
  1598.  
  1599.       *** Function:      FixedFont::load()
  1600.           Syntax:        int FixedFont::load(char *filename);
  1601.           Purpose:       Load a font and prepare it for use.
  1602.           Parameters:    The font file 'filename' loaded.
  1603.           Return value:  Returns 0 on error.
  1604.           Remarks:       None.
  1605.           See also:      None.
  1606.  
  1607.       *** Function:      FixedFont::width(char*)
  1608.           Syntax:        unsigned FixedFont::width(char *str);
  1609.           Purpose:       Return the width, in pixels, of a string.
  1610.           Parameters:    The string 'str' is analyzed.
  1611.           Return value:  Returns the width of 'str', in pixels.
  1612.           Remarks:       None.
  1613.           See also:      FixedFont::width(char), FixedFont::height(char*),
  1614.                          FixedFont::height(char), FixedFont::maxWidth(),
  1615.                          FixedFont::maxHeight()
  1616.  
  1617.       *** Function:      FixedFont::width(char)
  1618.           Syntax:        unsigned FixedFont::width(char ch);
  1619.           Purpose:       Return the width, in pixels, of a single
  1620.                          character.
  1621.           Parameters:    The character 'ch' is analyzed.
  1622.           Return value:  Returns the width of 'ch', in pixels.
  1623.           Remarks:       None.
  1624.           See also:      FixedFont::width(char*), FixedFont::height(char),
  1625.                          FixedFont::height(char*), FixedFont::maxWidth(),
  1626.                          FixedFont::maxHeight()
  1627.  
  1628.       *** Function:      FixedFont::maxWidth()
  1629.           Syntax:        unsigned maxWidth(void);
  1630.           Purpose:       Return the width of the widest character.
  1631.           Parameters:    None.
  1632.           Return value:  Returns the width of the widest character.
  1633.           Remarks:       None.
  1634.           See also:      FixedFont::maxHeight(void),
  1635.                          FixedFont::width(char*), FixedFont::width(char),
  1636.                          FixedFont::height(char*), FixedFont::height(char)
  1637.  
  1638.       *** Function:      FixedFont::height(char*)
  1639.           Syntax:        unsigned FixedFont::height(char *str);
  1640.           Purpose:       Return the height, in pixels, of a string.
  1641.           Parameters:    The string 'str' is analyzed.
  1642.           Return value:  Returns the depth of 'str', in pixels.
  1643.           Remarks:       None.
  1644.           See also:      FixedFont::height(char), FixedFont::width(char*),
  1645.                          FixedFont::height(char), FixedFont::maxHeight(),
  1646.                          FixedFont::maxWidth()
  1647.  
  1648.       *** Function:      FixedFont::height(char)
  1649.           Syntax:        unsigned FixedFont::height(char ch);
  1650.           Purpose:       Return the height, in pixels, of a single
  1651.                          character.
  1652.           Parameters:    The character 'ch' is analyzed.
  1653.           Return value:  Returns the height of 'ch', in pixels.
  1654.           Remarks:       None.
  1655.           See also:      FixedFont::height(char*), FixedFont::width(char),
  1656.                          FixedFont::width(char*), FixedFont::maxWidth(),
  1657.                          FixedFont::maxHeight()
  1658.  
  1659.       *** Function:      FixedFont::maxHeight()
  1660.           Syntax:        unsigned maxHeight(void);
  1661.           Purpose:       Return the height of the tallest character.
  1662.           Parameters:    None.
  1663.           Return value:  Returns the height of the tallest character.
  1664.           Remarks:       None.
  1665.           See also:      FixedFont::maxWidth(void),
  1666.                          FixedFont::height(char*), FixedFont::height(char),
  1667.                          FixedFont::width(char*), FixedFont::width(char)
  1668.  
  1669.       *** Function:      FixedFont::put(int, int, char*)
  1670.           Syntax:        void FixedFont::put(int x, int y, char *str);
  1671.           Purpose:       Write a string to the screen.
  1672.           Parameters:    The string 'str' will be written starting at
  1673.                          ('x','y').
  1674.           Return value:  None.
  1675.           Remarks:       The coordinate passed to this function specifies
  1676.                          the upper-left coordinate of the string.
  1677.           See also:      FixedFont::put(char);
  1678.  
  1679.       *** Function:      FixedFont::put(int, int, char)
  1680.           Syntax:        void FixedFont::put(int x, int y, char ch);
  1681.           Purpose:       Write a single character to the screen.
  1682.           Parameters:    The character 'ch' will be written at
  1683.                          ('x','y').
  1684.           Return value:  None.
  1685.           Remarks:       The coordinate passed to this function specifies
  1686.                          the upper-left coordinate of the character.
  1687.           See also:      FixedFont::put(char*);
  1688.  
  1689.       *** Function:      FixedFont::foreground(unsigned)
  1690.           Syntax:        void FixedFont::foreground(unsigned colour);
  1691.           Purpose:       Set the current foreground colour.
  1692.           Parameters:    The foreground colour will be set to 'colour'.
  1693.           Return value:  None.
  1694.           Remarks:       None.
  1695.           See also:      FixedFont::background(unsigned),
  1696.                          FixedFont::foreground(void),
  1697.                          FixedFont::background(void)
  1698.  
  1699.       *** Function:      FixedFont::foreground(void)
  1700.           Syntax:        unsigned FixedFont::foreground(void);
  1701.           Purpose:       Return the current foreground colour.
  1702.           Parameters:    None.
  1703.           Return value:  Returns the current foreground colour.
  1704.           Remarks:       None.
  1705.           See also:      FixedFont::background(void),
  1706.                          FixedFont::foreground(unsigned),
  1707.                          FixedFont::foreground(unsigned)
  1708.  
  1709.       *** Function:      FixedFont::background(unsigned)
  1710.           Syntax:        void FixedFont::background(unsigned colour);
  1711.           Purpose:       Set the current background colour.
  1712.           Parameters:    The background colour will be set to 'colour'.
  1713.           Return value:  None.
  1714.           Remarks:       None.
  1715.           See also:      FixedFont::foreground(unsigned),
  1716.                          FixedFont::background(void),
  1717.                          FixedFont::foreground(void)
  1718.  
  1719.       *** Function:      FixedFont::background(void)
  1720.           Syntax:        unsigned FixedFont::background(void);
  1721.           Purpose:       Return the current background colour.
  1722.           Parameters:    None.
  1723.           Return value:  Returns the current background colour.
  1724.           Remarks:       None.
  1725.           See also:      FixedFont::foreground(void),
  1726.                          FixedFont::background(unsigned),
  1727.                          FixedFont::foreground(unsigned)
  1728.  
  1729.       *** Function:      FixedFont::charAddr(char)
  1730.           Syntax:        void *FixedFont::charAddr(char ch);
  1731.           Purpose:       Return the address of the first byte of the
  1732.                          specified character's bitimage.
  1733.           Parameters:    The character 'ch' will have its address
  1734.                          calculated.
  1735.           Return value:  Returns the address of 'ch''s bitimage.
  1736.           Remarks:       None.
  1737.           See also:      None.
  1738.  
  1739.  
  1740.      Note that, at present, TGE's fonts are designed for use in 256-colour
  1741.      modes only.
  1742.  
  1743.  
  1744.  
  1745. BITMAP MANIPULATION
  1746. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1747.  
  1748.      Bitmaps can get boring when all you can do is display them.  TGE can
  1749.      scale bitmaps to different sizes, using the following function:
  1750.  
  1751.  *** Function:      scaleBitmap()
  1752.      Syntax:        void far *scaleBitmap(void *srcImage, unsigned newWide,
  1753.                     unsigned newDeep, void *destImage)
  1754.      Purpose:       Scale the given bitmap to the specified size.
  1755.      Parameters:    The image in 'srcImage' will be scaled to 'newWide'
  1756.                     pixels wide and 'newDeep' pixels deep.  The resulting
  1757.                     scaled image will be placed in 'destImage' if
  1758.                     'destImage' is non-NULL, or in a newly allocated block
  1759.                     of memory if 'destImage' is NULL.
  1760.      Return value:  Returns the address of the scaled image on success, or
  1761.                     NULL on error.  Note that NULL will never be returned
  1762.                     if 'destImage' is non-NULL.
  1763.      Remarks:       Results are undefined if either 'newWide' or 'newDeep'
  1764.                     is equal to zero.
  1765.      See also:      None.
  1766.  
  1767.  
  1768.      TGE also provides routines for determining an image's dimensions given
  1769.      its address:
  1770.  
  1771.  *** Function:      imageWidth
  1772.      Syntax:        unsigned imageWidth(void *image);
  1773.      Purpose:       Determine an image's width.
  1774.      Parameters:    This routine will determine the width of 'image'.
  1775.      Return value:  Returns the width, in pixels, of 'image'.
  1776.      Remarks:       This routine is implemented as a macro in TGE.H.
  1777.      See also:      imageHeight
  1778.  
  1779.  *** Function:      imageHeight
  1780.      Syntax:        unsigned imageHeight(void *image);
  1781.      Purpose:       Determine an image's height.
  1782.      Parameters:    This routine will determine the height of 'image'.
  1783.      Return value:  Returns the height, in pixels, of 'image'.
  1784.      Remarks:       This routine is implemented as a macro in TGE.H.
  1785.      See also:      imageWidth
  1786.  
  1787.  
  1788.  
  1789. PALETTE MANIPULATION
  1790. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1791.  
  1792.      TGE provides some palette manipulation routines, described below:
  1793.  
  1794.  
  1795.  *** Function:      fadePalette
  1796.      Syntax:        int fadePalette(unsigned step, void *inPal, void
  1797.                     *outPal, void *targetPal);
  1798.      Purpose:       Fade one palette into another.
  1799.      Parameters:    The palette at 'inPal' will be faded closer to the
  1800.                     palette at 'targetPal'.  The resulting palette will be
  1801.                     stored at 'outPal'.  Each of the colour components
  1802.                     which compose a palette colour will be incremented or
  1803.                     decremented by no more than the value in 'step'; thus,
  1804.                     higher 'step' values produce more rapid fading.
  1805.      Return value:  Returns 0 if fading is complete, or 1 if it isn't.
  1806.      Remarks:       Note that this function does not always complete the
  1807.                     fading with one call.  Code like this could be used:
  1808.                          while (fadePalette(1, in, out, target))
  1809.                          {
  1810.                            delay(10);
  1811.                            setBlockPalette(0, 255, out);
  1812.                            swap(in, out);
  1813.                            doSomeOtherProcessing();
  1814.                          }
  1815.      See also:      None.
  1816.  
  1817.  *** Function:      greyPalette
  1818.      Syntax:        void greyPalette(void *inPal, void *outPal);
  1819.      Purpose:       Produce a greyscale version of a palette.
  1820.      Parameters:    A greyscale version of the palette at 'inPal' will be
  1821.                     calculated, and stored at 'outPal'.
  1822.      Return value:  None, but the calculated greyscale palette will be at
  1823.                     'outPal' on return.
  1824.      Remarks:       Images designed with the input palette in mind will
  1825.                     look the same under the output greyscale palette,
  1826.                     except that they will be composed entirely of greys,
  1827.                     black, and white.
  1828.      See also:      None.
  1829.  
  1830.  *** Function:      rotatePalette
  1831.      Syntax:        void rotatePalette(int howMuch, void *inPal, void
  1832.                     *outPal)
  1833.      Purpose:       Rotate a palette.
  1834.      Parameters:    The palette at 'inPal' will be rotated by the value
  1835.                     'howMuch', and the resulting palette will be placed at
  1836.                     'outPal'.  'howMuch' can be negative or positive,
  1837.                     depending on which direction rotation will be
  1838.                     performed; for instance, a 'howMuch' value of 1 would
  1839.                     cause the value of colour 0 to move to colour 1, while
  1840.                     a 'howMuch' value of -1 would have the opposite effect.
  1841.      Return value:  None, but the rotated palette will be at 'outPal' on
  1842.                     return.
  1843.      Remarks:       This function will still operate correctly with
  1844.                     'howMuch' values which are greater than 255 or less
  1845.                     than -255.
  1846.      See also:      None.
  1847.  
  1848.  *** Function:      promotePalette
  1849.      Syntax:        void promotePalette(void *pal);
  1850.      Purpose:       Promote a 6-bit palette to 8-bit.
  1851.      Parameters:    The palette at 'pal' will be promoted.
  1852.      Return value:  None, but the promoted palette will be at 'pal' on
  1853.                     return.
  1854.      Remarks:       Some palettes are saved in 6-bit format, which uses
  1855.                     colour component values of 0..63; other programs, TGE
  1856.                     among them, use 8-bit format, which uses colour
  1857.                     component values of 0..255.  This function makes it
  1858.                     easy to use 6-bit palettes with TGE.
  1859.      See also:      demotePalette()
  1860.  
  1861.  *** Function:      demotePalette
  1862.      Syntax:        void demotePalette(void *pal);
  1863.      Purpose:       Demote an 8-bit palette to 6-bit.
  1864.      Parameters:    The palette at 'pal' will be demoted.
  1865.      Return value:  None, but the demoted palette will be at 'pal' on
  1866.                     return.
  1867.      Remarks:       Some palettes are saved in 6-bit format, which uses
  1868.                     colour component values of 0..63; other programs, TGE
  1869.                     among them, use 8-bit format, which uses colour
  1870.                     component values of 0..255.  This function makes it
  1871.                     easy to use 6-bit palettes with TGE.
  1872.      See also:      promotePalette()
  1873.  
  1874.  *** Function:      replaceColour
  1875.      Syntax:        void replaceColour(int ulx, int uly, int lrx, int lry,
  1876.                     unsigned oldColour, unsigned newColour);
  1877.      Purpose:       Replace all instances of a given colour within a
  1878.                     specified region.
  1879.      Parameters:    All instances of the colour 'oldColour' within the
  1880.                     rectangular region with upper-left corner ('ulx','uly')
  1881.                     and lower-right corner ('lrx','lry') will be replaced
  1882.                     with the colour 'newColour'.
  1883.      Return value:  None.
  1884.      Remarks:            Results are undefined if any coordinate of the
  1885.                     region is off-screen.
  1886.                          This function does not clip to within either
  1887.                     viewport.
  1888.                          This function does not actually change the
  1889.                     palette, but rather the pixel values themselves.
  1890.      See also:      None.
  1891.  
  1892.  
  1893.  
  1894. USING THE MOUSE
  1895. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1896.  
  1897.      TGE now provides support for interrupt-driven, definable mouse
  1898.      pointers.  In order to make use of this feature, some simple steps
  1899.      must be taken.
  1900.  
  1901.      The new mouse handler is designed to work in tandem with TGE's
  1902.      graphical functions.  Programs using the new mouse handler must first
  1903.      have successfully initialized graphics mode using TGE.  Both TGE.H and
  1904.      TGEMOUSE.H must be #included into a program using the mouse services.
  1905.  
  1906.      The mouse handler has to be initialized.  To do so, one function call
  1907.      is required:
  1908.  
  1909.           initNewMouse();
  1910.  
  1911.      For more information on initNewMouse(), refer to the mouse functions
  1912.      reference section.
  1913.  
  1914.      Next, the mouse driver must be informed of the screen dimensions, like
  1915.      this:
  1916.  
  1917.           setHorizLimitsMouse(0, OUTMAXX);
  1918.           setVertLimitsMouse(0, OUTMAXY);
  1919.  
  1920.      If desired, the pointer may then be positioned.  To center it on the
  1921.      screen, do this:
  1922.  
  1923.           setPosMouse(OUTMAXX/2, OUTMAXY/2);
  1924.  
  1925.      A pointer shape must then be selected.  TGE, as shipped, includes two
  1926.      arrow pointers and two target pointers; the file MOUSEPTR.C may easily
  1927.      be modified to allow more.  To select, for instance, the big arrow
  1928.      pointer, do this:
  1929.  
  1930.           setupMousePointer(BIG_ARROW_POINTER);
  1931.  
  1932.      The macro BIG_ARROW_POINTER is defined in TGEMOUSE.H; it expands to a
  1933.      number which is used by MOUSEPTR.C to identify which bitmap to use.
  1934.      Note that if exceptionally large (ie. larger than 512 bytes) pointers
  1935.      are used, a change must be made in NEWMOUSE.ASM; see that file for
  1936.      details.  If you would like to directly set a particular bitmap as the
  1937.      mouse pointer, you may use setPointerMouse(), described in the next
  1938.      section.
  1939.  
  1940.      Once things have been initialized, the use of the new mouse handler
  1941.      over the standard mouse driver can essentially be ignored; mouse
  1942.      driver services are obtained in exactly the same way.  The mouse
  1943.      interface functions are prototyped in TGEMOUSE.H, also using the macro
  1944.      method which allows function names to be changed simply by editing
  1945.      TGEMOUSE.H.
  1946.  
  1947.      Before exiting the program, the function deInitNewMouse() _must_ be
  1948.      called.  It is usually a very good idea to place deInitNewMouse() in
  1949.      the atexit() queue immediately after calling initNewMouse().
  1950.  
  1951.      Note that, since the pointer is drawn using TGE's putImageInv()
  1952.      function, the pointer will only appear when it is within the current
  1953.      viewport.
  1954.  
  1955.  
  1956.  
  1957. TGE'S MOUSE FUNCTION SET
  1958. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  1959.  
  1960.  *** Function:      initNewMouse()
  1961.      Syntax:        void initNewMouse(void);
  1962.      Purpose:       Initializes the new mouse handler.
  1963.      Parameters:    None.
  1964.      Return value:  None.
  1965.      Remarks:            A graphics driver must have been loaded prior to a
  1966.                     call to initNewMouse().
  1967.                          The new mouse handler requires that a Microsoft or
  1968.                     compatible mouse driver already be resident.  It
  1969.                     assumes that a mouse driver's presence will have been
  1970.                     tested beforehand.
  1971.                          initNewMouse() is really a simple macro; refer to
  1972.                     TGEMOUSE.H for the expansion of initNewMouse(void);
  1973.      See also:      deInitNewMouse(), enableNewMouse(), disableNewMouse()
  1974.  
  1975.  *** Function:      deInitNewMouse()
  1976.      Syntax:        void deInitNewMouse(void);
  1977.      Purpose:       Deactivate the new mouse handler, and leave all the
  1978.                     work up to the old driver.
  1979.      Parameters:    None.
  1980.      Return value:  None.
  1981.      Remarks:       This function must be called prior to program exit if
  1982.                     initNewMouse() had previously been called.
  1983.      See also:      initNewMouse(), enableNewMouse(), disableNewMouse()
  1984.  
  1985.  *** Function:      enableNewMouse()
  1986.      Syntax:        void enableNewMouse(void);
  1987.      Purpose:       Reactivate the new mouse handler following a call to
  1988.                     disableNewMouse().
  1989.      Parameters:    None.
  1990.      Return value:  None.
  1991.      Remarks:       None.
  1992.      See also:      disableNewMouse(), initNewMouse(), deInitNewMouse()
  1993.  
  1994.  *** Function:      disableNewMouse()
  1995.      Syntax:        void disableNewMouse(void);
  1996.      Purpose:       Temporarily deactivate the new mouse handler, to be
  1997.                     reactivated later by a call to enableNewMouse().
  1998.      Parameters:    None.
  1999.      Return value:  None.
  2000.      Remarks:       Following a call to this function, the new mouse
  2001.                     handler will cease trapping mouse driver interrupts and
  2002.                     moving the pointer.
  2003.      See also:      enableNewMouse(), initNewMouse(), deInitNewMouse()
  2004.  
  2005.  *** Function:      resetMouse()
  2006.      Syntax:        int resetMouse(void);
  2007.      Purpose:       Reset the mouse driver and hardware.
  2008.      Parameters:    None.
  2009.      Return value:  1 if mouse driver available, 0 otherwise.
  2010.      Remarks:       Following a call to this function, the mouse pointer is
  2011.                     hidden and positioned at the center of the screen.
  2012.      See also:      softResetMouse(), initNewMouse()
  2013.  
  2014.  *** Function:      getButtonsMouse()
  2015.      Syntax:        int getButtonsMouse(void);
  2016.      Purpose:       Return the number of buttons on the mouse.
  2017.      Parameters:    None.
  2018.      Return value:  Returns the number of buttons on the mouse.
  2019.      Remarks:       This function calls resetMouse(), and so the mouse
  2020.                     driver and hardware are re-initialized.
  2021.      See also:      resetMouse()
  2022.  
  2023.  *** Function:      showMouse()
  2024.      Syntax:        void showMouse(void);
  2025.      Purpose:       Show the mouse pointer.
  2026.      Parameters:    None.
  2027.      Return value:  None.
  2028.      Remarks:       Calls to showMouse() and hideMouse() are cumulative;
  2029.                     ie., if showMouse() is called twice, hideMouse() must
  2030.                     be called twice to hide the pointer again.
  2031.      See also:      hideMouse()
  2032.  
  2033.  *** Function:      hideMouse()
  2034.      Syntax:        void hideMouse(void);
  2035.      Purpose:       Hide the mouse pointer.
  2036.      Parameters:    None.
  2037.      Return value:  None.
  2038.      Remarks:       Calls to showMouse() and hideMouse() are cumulative;
  2039.                     ie., if showMouse() is called twice, hideMouse() must
  2040.                     be called twice to hide the pointer again.
  2041.      See also:      showMouse()
  2042.  
  2043.  *** Function:      getPosMouse()
  2044.      Syntax:        void getPosMouse(int far *x, int far *y);
  2045.      Purpose:       Get the current pointer coordinates.
  2046.      Parameters:    The current pointer x- and y-coordinates will be stored
  2047.                     in 'x' and 'y', respectively.
  2048.      Return value:  None.
  2049.      Remarks:       None.
  2050.      See also:      setPosMouse()
  2051.  
  2052.  *** Function:      setPosMouse()
  2053.      Syntax:        void setPosMouse(unsigned x, unsigned y);
  2054.      Purpose:       Set the current pointer coordinates.
  2055.      Parameters:    The pointer will be positioned at ('x','y').
  2056.      Return value:  None.
  2057.      Remarks:       None.
  2058.      See also:      getPosMouse()
  2059.  
  2060.  *** Function:      buttonMouse()
  2061.      Syntax:        int buttonMouse(void);
  2062.      Purpose:       Return whether or not any of the mouse buttons is down.
  2063.      Parameters:    None.
  2064.      Return value:  Returns true if at least one button is down, or zero if
  2065.                     none of them is down.
  2066.      Remarks:       None.
  2067.      See also:      leftButtonMouse(), rightButtonMouse(),
  2068.                     centerButtonMouse(), waitReleaseMouse()
  2069.  
  2070.  *** Function:      leftButtonMouse()
  2071.      Syntax:        int leftButtonMouse(void);
  2072.      Purpose:       Return the status of the left mouse button.
  2073.      Parameters:    None.
  2074.      Return value:  Returns true if the button is down, or zero if it is
  2075.                     up.
  2076.      Remarks:       None.
  2077.      See also:      buttonMouse(), rightButtonMouse(), centerButtonMouse(),
  2078.                     waitReleaseMouse()
  2079.  
  2080.  *** Function:      rightButtonMouse()
  2081.      Syntax:        int rightButtonMouse(void);
  2082.      Purpose:       Return the status of the right mouse button.
  2083.      Parameters:    None.
  2084.      Return value:  Returns true if the button is down, or zero if it is
  2085.                     up.
  2086.      Remarks:       None.
  2087.      See also:      buttonMouse(), leftButtonMouse(), centerButtonMouse(),
  2088.                     waitReleaseMouse()
  2089.  
  2090.  *** Function:      centerButtonMouse()
  2091.      Syntax:        int centerButtonMouse(void);
  2092.      Purpose:       Return the status of the center mouse button.
  2093.      Parameters:    None.
  2094.      Return value:  Returns true if the button is down, or zero if it is
  2095.                     up.
  2096.      Remarks:       None.
  2097.      See also:      buttonMouse(), leftButtonMouse(), rightButtonMouse(),
  2098.                     waitReleaseMouse()
  2099.  
  2100.  *** Function:      buttonPressMouse()
  2101.      Syntax:        unsigned buttonPressMouse(unsigned button, int far *x,
  2102.                     int far *y);
  2103.      Purpose:       Return the number of times the specified button has
  2104.                     been pressed since the last call to this function (with
  2105.                     the same button parameter), and store the coordinates
  2106.                     of the last press.
  2107.      Parameters:    The button 'button' is checked, and may be any of
  2108.                     LEFTBUTTON, RIGHTBUTTON, and CENTERBUTTON, which are
  2109.                     defined in TGEMOUSE.H.  The position of the last press
  2110.                     will be stored in ('x','y').
  2111.      Return value:  Returns the number of times the specified button has
  2112.                     been pressed since the last call to this function (with
  2113.                     the same button parameter).
  2114.      Remarks:       None.
  2115.      See also:      buttonReleaseMouse()
  2116.  
  2117.  *** Function:      buttonReleaseMouse()
  2118.      Syntax:        unsigned buttonReleaseMouse(unsigned button, int far
  2119.                     *x, int far *y);
  2120.      Purpose:       Return the number of times the specified button has
  2121.                     been released since the last call to this function
  2122.                     (with the same button parameter), and store the
  2123.                     coordinates of the last press.
  2124.      Parameters:    The button 'button' is checked, and may be any of
  2125.                     LEFTBUTTON, RIGHTBUTTON, and CENTERBUTTON, which are
  2126.                     defined in TGEMOUSE.H.  The position of the last
  2127.                     release will be stored in ('x','y').
  2128.      Return value:  Returns the number of times the specified button has
  2129.                     been released since the last call to this function
  2130.                     (with the same button parameter).
  2131.      Remarks:       None.
  2132.      See also:      buttonPressMouse()
  2133.  
  2134.  *** Function:      waitReleaseMouse()
  2135.      Syntax:        void waitReleaseMouse(int button);
  2136.      Purpose:       If the specified button is not already up, wait until
  2137.                     it is released, then return.
  2138.      Parameters:    The button 'button' is checked, and may be any of
  2139.                     LEFTBUTTON, RIGHTBUTTON, and CENTERBUTTON, which are
  2140.                     defined in TGEMOUSE.H.
  2141.      Return value:  None.
  2142.      Remarks:       None.
  2143.      See also:      buttonMouse(), leftButtonMouse(), rightButtonMouse(),
  2144.                     centerButtonMouse()
  2145.  
  2146.  *** Function:      setHorizLimitsMouse()
  2147.      Syntax:        void setHorizLimitsMouse(unsigned min, unsigned max);
  2148.      Purpose:       Set the minimum and maximum horizontal coordinates for
  2149.                     the pointer.
  2150.      Parameters:    The minimum horizontal coordinate will be set to 'min',
  2151.                     and the maximum to 'max'.
  2152.      Return value:  None.
  2153.      Remarks:       None.
  2154.      See also:      setVertLimitsMouse()
  2155.  
  2156.  *** Function:      setVertLimitsMouse()
  2157.      Syntax:        void setVertLimitsMouse(unsigned min, unsigned max);
  2158.      Purpose:       Set the minimum and maximum vertical coordinates for
  2159.                     the pointer.
  2160.      Parameters:    The minimum vertical coordinate will be set to 'min',
  2161.                     and the maximum to 'max'.
  2162.      Return value:  None.
  2163.      Remarks:       None.
  2164.      See also:      setHorizLimitsMouse()
  2165.  
  2166.  *** Function:      setPointerMouse()
  2167.      Syntax:        void setPointerMouse(int xOff, int yOff, void far *p);
  2168.      Purpose:       Set the shape of the pointer.
  2169.      Parameters:    The image pointed to by 'p' will be the pointer bitmap. 
  2170.                     ('xOff','yOff') is the offset, relative to the upper-
  2171.                     left corner of the bitmap, of the "hot spot" -- the
  2172.                     pixel where the pointer is actually registered as
  2173.                     being.  (For instance, the standard arrow pointer has
  2174.                     its hot spot in the upper-left, while a crosshairs
  2175.                     pointer would have it towards the middle.)
  2176.      Return value:  None.
  2177.      Remarks:       The mouse pointer should be hidden when a call to this
  2178.                     function is made.
  2179.      See also:      None.
  2180.  
  2181.  *** Function:      getSaveSizeMouse()
  2182.      Syntax:        unsigned getSaveSizeMouse(void);
  2183.      Purpose:       Return the size of the buffer necessary to store the
  2184.                     state of the mouse driver.
  2185.      Parameters:    None.
  2186.      Return value:  Returns the size of the buffer.
  2187.      Remarks:       If a program using TGE and the new mouse handling
  2188.                     routines is to run another program, for instance
  2189.                     shelling to DOS, the ensuing procedure should be
  2190.                     followed:  call disableNewMouse(), call
  2191.                     getSaveSizeMouse(), allocate a block of memory with the
  2192.                     size returned by getSaveSizeMouse(), call
  2193.                     saveStateMouse(), run the program, call
  2194.                     restoreStateMouse(), free the block of memory, then
  2195.                     call enableNewMouse().
  2196.      See also:      saveStateMouse(), restoreStateMouse()
  2197.  
  2198.  *** Function:      saveStateMouse()
  2199.      Syntax:        void saveStateMouse(void far *buf);
  2200.      Purpose:       Save the current state of the mouse driver.
  2201.      Parameters:    The block of memory pointed to by 'buf' will be used to
  2202.                     store the state data.  Its length should be obtained by
  2203.                     calling getSaveSizeMouse().
  2204.      Return value:  None.
  2205.      Remarks:       If a program using TGE and the new mouse handling
  2206.                     routines is to run another program, for instance
  2207.                     shelling to DOS, the ensuing procedure should be
  2208.                     followed:  call disableNewMouse(), call
  2209.                     getSaveSizeMouse(), allocate a block of memory with the
  2210.                     size returned by getSaveSizeMouse(), call
  2211.                     saveStateMouse(), run the program, call
  2212.                     restoreStateMouse(), free the block of memory, then
  2213.                     call enableNewMouse().
  2214.      See also:      getSaveSizeMouse(), restoreStateMouse()
  2215.  
  2216.  *** Function:      restoreStateMouse()
  2217.      Syntax:        void restoreStateMouse(void far *buf);
  2218.      Purpose:       Restore the state of the mouse driver from a buffer
  2219.                     previously filled by saveStateMouse().
  2220.      Parameters:    The block of memory pointed to by 'buf' stores the
  2221.                     state data.
  2222.      Return value:  None.
  2223.      Remarks:       If a program using TGE and the new mouse handling
  2224.                     routines is to run another program, for instance
  2225.                     shelling to DOS, the ensuing procedure should be
  2226.                     followed:  call disableNewMouse(), call
  2227.                     getSaveSizeMouse(), allocate a block of memory with the
  2228.                     size returned by getSaveSizeMouse(), call
  2229.                     saveStateMouse(), run the program, call
  2230.                     restoreStateMouse(), free the block of memory, then
  2231.                     call enableNewMouse().
  2232.      See also:      getSaveSizeMouse, saveStateMouse
  2233.  
  2234.  *** Function:      setRatioMouse()
  2235.      Syntax:        void setRatioMouse(unsigned horiz, unsigned vert);
  2236.      Purpose:       Set the mouse sensitivity, in units of mickeys per 8
  2237.                     pixels of pointer movement.  (A mickey is the unit used
  2238.                     to measure mouse movement.)
  2239.      Parameters:    The horizontal mickeys to pixels ratio will be set to
  2240.                     'horiz', and the vertical to 'vert'.
  2241.      Return value:  None.
  2242.      Remarks:       None.
  2243.      See also:      getSensitivityMouse()
  2244.  
  2245.  *** Function:      getSensitivityMouse()
  2246.      Syntax:        void getSensitivityMouse(unsigned *horiz, unsigned
  2247.                     *vert, unsigned *doubleSpeed);
  2248.      Purpose:       Get the mouse sensitivity, in units of mickeys per 8
  2249.                     pixels of pointer movement.  (A mickey is the unit used
  2250.                     to measure mouse movement.)  The mouse double speed
  2251.                     threshold (the minimum number of mickeys per second of
  2252.                     motion before pointer movement is doubled) is retrieved
  2253.                     as well.
  2254.      Parameters:    The horizontal mickeys to pixels ratio will be stored
  2255.                     in 'horiz', the vertical in 'vert', and the double
  2256.                     speed threshold in 'doubleSpeed'.
  2257.      Return value:  None.
  2258.      Remarks:       None.
  2259.      See also:      setRatioMouse()
  2260.  
  2261.  *** Function:      softResetMouse()
  2262.      Syntax:        void softResetMouse(void);
  2263.      Purpose:       Reset the mouse driver, but not the hardware.
  2264.      Parameters:    None.
  2265.      Return value:  None.
  2266.      Remarks:       This function is equivalent to resetMouse(), except in
  2267.                     that it performs no initialization of the mouse
  2268.                     hardware.
  2269.      See also:      resetMouse()
  2270.  
  2271.  
  2272.      Note that since these function names are actually macros, they may
  2273.      easily be changed to suit individual preferences by editing
  2274.      TGEMOUSE.H.
  2275.  
  2276.  
  2277.  
  2278. ADDITIONAL FEATURES IN THE REGISTERED VERSION
  2279. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2280.  
  2281.      In addition to technical support and usage rights, registered users
  2282.      may use the registered version of TGE.  Not only does the registered
  2283.      version of TGE include complete source code for the TGE library and an
  2284.      extra font not found in the shareware version, it also includes a
  2285.      handy memory-saving feature not available in the shareware version:
  2286.  
  2287.      Registered users can save up to about 22 kb of memory by selectively
  2288.      commenting out #defines in TGE.H and compiling the TGE library.
  2289.      Following is a list of symbols and the features they disable when
  2290.      they're not #defined:
  2291.           TGE_USE_VIRTUAL_SCREENS       Virtual screen support.
  2292.           TGE_USE_OUTPUT_MODES          Output mode support.
  2293.           TGE_USE_REGION_FILLS          fillRegion().
  2294.           TGE_USE_IMAGES                Bitmap-related functions.
  2295.           TGE_USE_ELLIPSES              Ellipse- and circle-drawing.
  2296.           TGE_USE_COLOUR_APPROXIMATION  colourCloseTo() and
  2297.                                         colourCloseToX().
  2298.           TGE_USE_PUTVERTLINE           putVertLine() and other
  2299.                                         xxxVertLine() functions.
  2300.      The source for the disabled features is simply not compiled, and so
  2301.      does not waste space in your executables or in memory.  Remember to
  2302.      recompile the TGE library after making a change!
  2303.  
  2304.  
  2305.  
  2306. CREATING FONTS
  2307. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2308.  
  2309.      Creating fonts is not easy, but the necessary information is outlined
  2310.      below.
  2311.  
  2312.      For variable-size 256-colour fonts:
  2313.      ──────────────────────────────────
  2314.           First, you should make a working directory for your font's data
  2315.           files.  For the sake of example, I will assume that you are
  2316.           trying to create MYFONT.FNT.
  2317.  
  2318.           Second, draw a bitmap for each of the 256 ASCII characters which
  2319.           you would like to exist in the font; if you won't be using a
  2320.           character, feel free to not bother drawing a bitmap for it.  Each
  2321.           bitmap should be as small as possible, so be sure not to leave
  2322.           any extra space around the character.  Use colour zero as the
  2323.           background colour, or some other colour if you would like the
  2324.           font to have a coloured background.  Save each of these bitmaps
  2325.           as a PCX file in the working directory.  Note that all character
  2326.           bitmaps must use the same colour palette.
  2327.  
  2328.           Third, convert the PCX files to RAW files by using PCX2RAW; to do
  2329.           so, type 'PCX2RAW *'.
  2330.  
  2331.           Fourth, you must rename one of the PAL files produced by PCX2RAW
  2332.           to MYFONT.PAL (remember MYFONT.FNT is the font you're creating).
  2333.           If you wish, you may delete all the other PAL files, so long as
  2334.           you leave MYFONT.PAL intact.
  2335.  
  2336.           Fifth, you must create MYFONT.OFF, the character offset
  2337.           description file.  This text file consists of 256 lines, each
  2338.           containing a single integer (either positive or zero), followed
  2339.           by a newline.  Each line contains its corresponding character's
  2340.           "offset from top" value; the first line is for character 0, the
  2341.           second is for character 1, and so on.  Given the (x,y)
  2342.           coordinates at which to put a character from the font, the
  2343.           "offset from top" is the value to add to the y coordinate before
  2344.           putImageInv() is called to display the character's bitmap.  The
  2345.           "offset from top" is used to make character bitmaps be written
  2346.           lower down on the screen than other bitmaps; for instance, the
  2347.           period character's offset would be greater than an asterisk's
  2348.           offset, because a period is lower down than an asterisk.
  2349.  
  2350.           Finally, you must create the font file MYFONT.FNT; to do so, type
  2351.           'MAKEFONT myfont'.
  2352.  
  2353.  
  2354.      For fixed-size monochrome fonts:
  2355.      ───────────────────────────────
  2356.           TGE's font definition files must have a certain format which will
  2357.           be outlined below.  (Note that a fixed font consists of 256
  2358.           monochrome characters, each with the same dimensions.)
  2359.  
  2360.           The font file header consists of three fields of defined length.
  2361.           The first of these fields is the eight-byte font definition file
  2362.           signature string, which must be "TGEFONT1", without quotes or
  2363.           terminating null character.  The next field is a two-byte
  2364.           unsigned integer which holds the width of a character in pixels.
  2365.           The last field is also a two-byte integer, holding the height of
  2366.           a character in pixels.
  2367.  
  2368.           The remainder of the file consists of font data.  (If you have
  2369.           done advanced text programming before, you may recognize this
  2370.           data organization as the format used by the video BIOS.)  The
  2371.           characters are stored starting at character 0, all the way up to
  2372.           255.  Each of the characters is stored starting with the
  2373.           uppermost row, all the way down to the bottom row.  Each row is
  2374.           stored left to right, with the leftmost pixel in the most
  2375.           significant bit of the first byte in the row, and the rightmost
  2376.           pixel in the least significant bit of the last byte in the row.
  2377.           A 1 bit represents a foreground pixel, while a 0 bit represents a
  2378.           background pixel.  Note that, at present, font row widths must be
  2379.           evenly divisible by 8; pad with 0 bits if necessary.
  2380.  
  2381.           Image data for all 256 of the ASCII characters must be present in
  2382.           the file; if you won't be needing some of them, feel free to
  2383.           store zero bytes (or random bytes, if you're imaginative) as
  2384.           their image data.
  2385.  
  2386.  
  2387.  
  2388. USING PCX2RAW AND GRAPHICS FILES
  2389. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2390.  
  2391.      The PCX2RAW utility provides a simple way to convert 256-colour images
  2392.      in PCX format into a format usable by TGE.  It is used like this:
  2393.  
  2394.           pcx2raw filename[.pcx]
  2395.  
  2396.      Given the PCX file FILENAME.PCX, PCX2RAW will create two new files in
  2397.      the same directory as FILENAME.PCX:  FILENAME.PAL which contains the
  2398.      colour palette from FILENAME.PCX, and FILENAME.RAW which is a TGE
  2399.      format bitmap of the image in FILENAME.PCX.  Following is a discussion
  2400.      of the PAL and RAW file formats, and how to use TGE's functions to
  2401.      access them.
  2402.  
  2403.  
  2404.      The PAL file is organized like this:
  2405.  
  2406.          Element size    Element description
  2407.          ------------    -------------------
  2408.            3 bytes           colour 0
  2409.            3 bytes           colour 1
  2410.                         .
  2411.                         .
  2412.                         .
  2413.            3 bytes           colour 254
  2414.            3 bytes           colour 255
  2415.  
  2416.      Each 3-byte element consists of the red, green, and blue colour
  2417.      components, in that order.  Each of these components is an unsigned
  2418.      char.  Code to load a PAL file is included in RAWFILE.C; the function
  2419.      description follows:
  2420.  
  2421.  *** Function:      loadPalFile()
  2422.      Syntax:        void far *loadPalFile(char *filename, void far *addr);
  2423.      Purpose:       Load a 768-byte palette file into memory.
  2424.      Parameters:    The palette data file 'filename' will be loaded into
  2425.                     the memory block at 'addr' (if 'addr' != NULL), or into
  2426.                     a newly allocated memory block (if 'addr' == NULL).
  2427.      Return value:  Returns the address of the loaded palette on success,
  2428.                     or NULL on error.
  2429.      Remarks:       If 'addr' is NULL, be sure to free() the allocated
  2430.                     memory block when the palette information is no longer
  2431.                     needed.
  2432.      See also:      loadPcxFilePal(), loadRawFile(), displayRawFile(),
  2433.                     loadPcxFile(), displayPcxFile()
  2434.  
  2435.  
  2436.      The RAW file is organized in exactly the same way as the bitmaps used
  2437.      by putImage() and its associated functions:  2 bytes for the image
  2438.      width, then 2 bytes for the image height, then width*height bytes (one
  2439.      per pixel) for the image information itself; the pixels are in order
  2440.      from left to right and from top to bottom, as one would read a book.
  2441.      The image dimension fields are both unsigned shorts, and are measured
  2442.      in pixels.  Code to deal with RAW files is included in RAWFILE.C; the
  2443.      function descriptions follow:
  2444.  
  2445.  *** Function:      loadRawFile()
  2446.      Syntax:        void far *loadRawFile(char *filename);
  2447.      Purpose:       Load a RAW image file into memory.
  2448.      Parameters:    The RAW image file 'filename' will be loaded into a
  2449.                     newly allocated memory block.
  2450.      Return value:  Returns the address of the loaded image on success, or
  2451.                     NULL on error.
  2452.      Remarks:       Be sure to free() the allocated memory block when the
  2453.                     image information is no longer needed.
  2454.      See also:      saveRawFile(), displayRawFile(), loadPcxFile(),
  2455.                     loadPalFile()
  2456.  
  2457.  *** Function:      displayRawFile()
  2458.      Syntax:        int displayRawFile(int x, int y, char *filename);
  2459.      Purpose:       Display a RAW image file.
  2460.      Parameters:    The RAW image file 'filename' will be displayed with
  2461.                     its upper-left corner at ('x','y').  Clipping is
  2462.                     performed.
  2463.      Return value:  Returns the 1 on success, or 0 on error.
  2464.      Remarks:       Since this function uses standard TGE output routines,
  2465.                     it can display to virtual screens as well as the real
  2466.                     screen.
  2467.      See also:      loadRawFile(), displayPcxFile(), loadPalFile()
  2468.  
  2469.  *** Function:      saveRawFile()
  2470.      Syntax:        int saveRawFile(char *filename, void *image);
  2471.      Purpose:       Save a RAW image to disk.
  2472.      Parameters:    The image at 'image' will be written to the RAW image
  2473.                     file 'filename'.
  2474.      Return value:  Returns 0 on error.
  2475.      Remarks:       None.
  2476.      See also:      loadRawFile(), loadPcxFile(), displayRawFile()
  2477.  
  2478.  
  2479.      TGE also includes routines to deal directly with PCX files:
  2480.  
  2481.  *** Function:      loadPcxFilePal()
  2482.      Syntax:        void far *loadPcxFilePal(char *filename, void far *addr);
  2483.      Purpose:       Load a 768-byte palette from a PCX file into memory.
  2484.      Parameters:    The palette data 'filename' will be loaded into the
  2485.                     memory block at 'addr' (if 'addr' != NULL), or into a
  2486.                     newly allocated memory block (if 'addr' == NULL).
  2487.      Return value:  Returns the address of the loaded palette on success,
  2488.                     or NULL on error.
  2489.      Remarks:       If 'addr' is NULL, be sure to free() the allocated
  2490.                     memory block when the palette information is no longer
  2491.                     needed.
  2492.      See also:      loadPalFile(), loadPcxFile(), displayPcxFile(),
  2493.                     loadRawFile(), displayRawFile()
  2494.  
  2495.  *** Function:      loadPcxFile()
  2496.      Syntax:        void far *loadPalFile(char *filename, void *palette);
  2497.      Purpose:       Load a PCX image file, and its palette if requested,
  2498.                     into memory.
  2499.      Parameters:    The PCX image file 'filename' will be loaded into a
  2500.                     newly allocated memory block.  If 'palette' is
  2501.                     non-NULL, the 768 bytes of palette data from the PCX
  2502.                     file will be loaded into the memory area at 'palette'.
  2503.      Return value:  Returns the address of the loaded image on success, or
  2504.                     NULL on error.  If 'palette' was non-NULL, a copy of
  2505.                     the palette will be at the memory area pointed to by
  2506.                     'palette' on return.
  2507.      Remarks:       Be sure to free() the allocated memory block when the
  2508.                     image information is no longer needed.
  2509.      See also:      displayPcxFile(), loadPcxFilePal(), loadRawFile(),
  2510.                     displayRawFile(), loadPalFile()
  2511.  
  2512.  *** Function:      displayPcxFile()
  2513.      Syntax:        int displayPcxFile(int x, int y, char *filename);
  2514.      Purpose:       Display a PCX image file.
  2515.      Parameters:    The PCX image file 'filename' will be displayed with
  2516.                     its upper-left corner at ('x','y').  Clipping is
  2517.                     performed.
  2518.      Return value:  Returns the 1 on success, or 0 on error.
  2519.      Remarks:            Since this function uses standard TGE output
  2520.                     routines, it can display to virtual screens as well as
  2521.                     the real screen.
  2522.                          The image is displayed using the current palette,
  2523.                     which is not necessarily the same as that of the PCX
  2524.                     file.
  2525.      See also:      loadPcxFile(), displayRawFile(), loadRawFile()
  2526.  
  2527.  
  2528.  
  2529. WHICH SVGA VIDEO DRIVER SHOULD I USE?
  2530. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2531.  
  2532.      The most important change in this release is the addition of video
  2533.      drivers dedicated to accessing SVGA video modes though VESA BIOS
  2534.      Extensions (VBEs).  When these drivers are used, TGE uses the VBEs to
  2535.      access the video card through a standardized method, using code
  2536.      written by video card vendors for their video cards; thus, TGE does
  2537.      not have to access every card directly through hardware.  Using these
  2538.      VBE drivers is generally recommended, since doing so will allow TGE to
  2539.      support any video card which supports VBEs (which most do these days),
  2540.      which also reducing the probability of bugs.  So, unless you have a
  2541.      good reason not to use the VBE drivers, it is advisable to use them.
  2542.  
  2543.      The VBE drivers are as follows:
  2544.  
  2545.          VBE100.DRV                Driver for VBE SVGA 640x400x256.
  2546.          VBE101.DRV                Driver for VBE SVGA 640x480x256.
  2547.          VBE103.DRV                Driver for VBE SVGA 800x600x256.
  2548.          VBE105.DRV                Driver for VBE SVGA 1024x768x256.
  2549.          VBE107.DRV                Driver for VBE SVGA 1280x1024x256.
  2550.  
  2551.  
  2552.  
  2553. CONTACTING THE AUTHOR
  2554. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2555.  
  2556.      I would appreciate hearing any questions, comments, bug reports, or
  2557.      suggestions for improvement.  If you have any, feel free to contact
  2558.      me; I can be reached via any of the methods below.  When reporting
  2559.      bugs, please be sure to mention the version of TGE to which you are
  2560.      referring; also, if possible, please include detailed descriptions of
  2561.      the problem and of your video hardware configuration.  If you have a
  2562.      video card which is not directly supported by TGE, I would appreciate
  2563.      it if you would send me programming information about your card and/or
  2564.      code to deal with it.
  2565.  
  2566.           Snail mail:      Matthew Hildebrand
  2567.                            4 College St.
  2568.                            St. Catharines, ON
  2569.                            Canada   L2R 2W7
  2570.  
  2571.           Internet mail:   mphildeb@undergrad.math.uwaterloo.ca
  2572.  
  2573.           Fidonet mail:    1:247/128.2
  2574.                Please use netmail, rather than posting in an echo.
  2575.  
  2576.           BBS:             (905)-935-6628
  2577.                I am not the sysop of idiot savant BBS, but I will receive
  2578.                messages left there for me.  The BBS runs a 14400 bps
  2579.                V.32bis modem.  You can pick up the latest versions of my
  2580.                software packages here.
  2581.  
  2582.           Telephone:       (905)-687-8736
  2583.                Please keep in mind the time zone difference, if any, when
  2584.                calling; I'm in Eastern Standard Time.
  2585.  
  2586.  
  2587.  
  2588. OBTAINING THE NEWEST VERSION OF TGE
  2589. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2590.  
  2591.      The most recent distributed copy of TGE is available via first-call
  2592.      download from (905)-935-6628 (14400 bps V.32bis), or via file request
  2593.      from Fidonet node 1:247/128 (14400 bps V.32bis) using the magic file
  2594.      name "TGE"; unlisted nodes and points are welcome.  TGE is also
  2595.      distributed through the Fidonet file echo PDNCEE.
  2596.  
  2597.      If, after you have registered, you are interested in receiving new
  2598.      versions of TGE as they are released, an easy method is now available.
  2599.      For $3 per mailing (to cover the disk, envelope, and postage), I will
  2600.      mail copies of new versions as they are released, on either a 3.5" or
  2601.      a 5.25" disk.  The $3 per mailing may be included with the initial
  2602.      registration fee, with instructions to mail newer versions as they are
  2603.      released, or mailed later with a request for a copy of the newest
  2604.      version.  Please ensure that the $3 is paid in either US or Canadian
  2605.      funds; payment by cash, money order (use an international money order
  2606.      if necessary), or cheque drawn on a US or Canadian bank is acceptable.
  2607.  
  2608.      Alternatively, it is possible to receive notifications of updates but
  2609.      not the updates themselves.  For $1 per mailing (to cover the envelope
  2610.      and postage), I will mail notifications of new versions when they are
  2611.      released.  The $1 per mailing may be included with the initial
  2612.      registration fee, with instructions to mail notifications as new
  2613.      versions are released, or mailed later with similar instructions.
  2614.      Again, please ensure that the $1 is paid in either US or Canadian
  2615.      funds; payment by cash, money order (use an international money order
  2616.      if necessary), or cheque drawn on a US or Canadian bank is acceptable.
  2617.  
  2618.  
  2619.  
  2620. TROUBLESHOOTING
  2621. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2622.  
  2623.      Q.   I get linker errors.  What's happening?
  2624.  
  2625.      A.   BEFORE ATTEMPTING TO USE THE C++ PORTIONS OF TGE, BE SURE TO
  2626.           RECOMPILE THEM ON YOUR MACHINE.  THIS IS NECESSARY TO AVOID WHAT
  2627.           APPEARS TO BE A BUG IN TURBO LINKER.  IN ORDER TO RECOMPILE THE
  2628.           C++ PORTIONS, RUN UPDATE.BAT FROM THE TGE\LIB DIRECTORY.
  2629.  
  2630.  
  2631.      Q.   TGE doesn't seem to be displaying SVGA graphics correctly.
  2632.  
  2633.      A.   TGE is known to get confused by certain video chipsets.  Try
  2634.           using the appropriate VBE (VESA BIOS Extensions) driver, one of
  2635.           the VBE*.DRV series.
  2636.  
  2637.  
  2638.      Q.   I can't get initGraphics() to return a success code.  Why?
  2639.  
  2640.      A.   If you're using one of the VBE*.DRV files (drivers using the VESA
  2641.           BIOS Extensions), then you're probably trying to run your program
  2642.           on a machine without VBE services.  There may be a VBE TSR which
  2643.           came with your video card; if not, or if it doesn't work, try
  2644.           using UNIVBE (refer to UNIVBE.DOC for details).
  2645.  
  2646.  
  2647.      Q.   I'm a registered user, so I have a copy of TGE's source code.
  2648.           I've recompiled the library, and now putImage() and putImageInv()
  2649.           don't work correctly.  Why not?
  2650.  
  2651.      A.   When TGEFUNCS.C is compiled by Turbo C++ 3.0, putImage() and
  2652.           putImageInv() do not work correctly.  When informed of this bug,
  2653.           I stepped through the offending code at the assembly level, and
  2654.           discovered that this problem is caused by a bug in TC++, not TGE.
  2655.           The miscompiled lines of TGE.C are perfectly legal C statements;
  2656.           when TGE.C is compiled by my compiler (Borland C++ 2.0), TGE
  2657.           works correctly.  Using the TGEFUNCS.OBJ contained within one of
  2658.           the TGE library files, rather than OBJ files compiled by Turbo
  2659.           C++ 3.0, should solve the problem.
  2660.  
  2661.  
  2662.  
  2663. ACKNOWLEDGEMENT
  2664. ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
  2665.  
  2666.      There are many people whom I would like to thank for their
  2667.      suggestions, beta-testing, patience, registrations, and help with
  2668.      distribution.  You know who you are.
  2669.  
  2670.  
  2671.  
  2672. LEGAL STUFF
  2673. ▀▀▀▀▀▀▀▀▀▀▀
  2674.  
  2675.      The Graphics Engine and its documentation are Copyright (c) 1993-1995
  2676.      by Matthew Hildebrand.
  2677.  
  2678.      All software and documentation associated with The Graphics Engine is
  2679.      provided "as is":  ie., it is provided without warranty of any kind,
  2680.      not even an implied warranty of merchantability or fitness for any
  2681.      purpose.  The Author (Matthew Hildebrand) disclaims all warranties,
  2682.      both express and implied, including but not limited to warranties
  2683.      regarding The Graphics Engine's merchantability or fitness for any
  2684.      particular purpose.
  2685.  
  2686.      The author may not be held liable for any damage or misfortune related
  2687.      to the use of this software.  Any usage of any or all of The Graphics
  2688.      Engine is done entirely at the user's risk.
  2689.  
  2690.      All registered trademarks in this document belong to their respective
  2691.      owners.
  2692.  
  2693.  
  2694.  
  2695. End of document.
  2696.